@squadbase/vantage 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -10,6 +10,6 @@ import 'react';
  */
 
 /** Framework version, kept in sync with package.json at build time. */
-declare const VERSION = "0.2.1";
+declare const VERSION = "0.2.2";
 
 export { VERSION };

package/dist/index.js

@@ -6,7 +6,7 @@ function definePage(config) {
 }
 
 // src/index.ts
-var VERSION = "0.2.1";
+var VERSION = "0.2.2";
 
 export { VERSION, definePage };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.1\"\n"]}
+{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.2\"\n"]}

package/docs/en/agent-skills.md

@@ -22,12 +22,29 @@ The skills ship inside the `@squadbase/vantage` package. `vantage add skill` cop
 your app. They land **directly under the project root** by default; `--dir` puts them elsewhere.
 
 ```bash
-vantage add skill --all                       # every bundled skill, under the root
+vantage add skill                             # list the skills and where they sit (writes nothing)
+vantage add skill --all                       # every skill that isn't placed yet, under the root
 vantage add skill vantage-app                 # a single skill by name
 vantage add skill --all --dir .claude/skills  # where Claude Code looks for them
-vantage add skill vantage-app --force         # overwrite an existing copy
+vantage add skill --all --force               # refresh the placed copies in place
 ```
 
+**The destination is scanned for, not assumed.** `add skill` walks the project first (skipping
+`node_modules` and friends) and **skips any skill that is already placed, reporting where it is** —
+under the root, under `.claude/skills/`, under `.squadbase/skills/`, it doesn't matter, so
+**re-running never creates a second copy**. Drop the name to get just the list:
+
+```text
+$ vantage add skill
+Bundled skills:
+  vantage-add-feature  .claude/skills/vantage-add-feature/
+  vantage-app          .claude/skills/vantage-app/
+  vantage-pitfalls     not placed
+```
+
+With `--force`, the copies that were found are rewritten **where they are** (an explicit `--dir`
+still wins as the destination).
+
 A `--dir` path resolves from the project root (absolute paths work too). To have Claude Code pick
 them up automatically, place them in `.claude/skills/`:
 
@@ -54,8 +71,8 @@ skill based on the task at hand. For other agents, pass whatever directory that
 
 - **The source of truth lives in the package.** Skills are distributed and updated together with
   the framework version, so bumping `@squadbase/vantage` gets you the latest procedures. To refresh
-  copies you've already placed, run `vantage add skill --all --force` with the same `--dir` you
-  used originally.
+  copies you've already placed, run `vantage add skill --all --force` — the destination is scanned
+  for, so you don't have to remember the `--dir` you used originally.
 - **The Squadbase template ships them pre-placed.** Apps created from the template already contain
   `.claude/skills/`. For a hand-made app, add them with `vantage add skill`.
 

package/docs/en/changelog.md

@@ -9,6 +9,37 @@ What changed in each Vantage release. Newest is on top.
 > minor release may include backwards-incompatible changes. A patch is limited to
 > backwards-compatible additions and bug fixes.
 
+## v0.2.2
+
+`vantage add skill` now scans for where the skills already are, and charts follow
+stylesheet swaps too. Both are backwards-compatible.
+
+### Changed
+
+- **`vantage add skill` looks for placed skills before copying** — it walks the
+  project for `<skill>/SKILL.md` and **skips anything already placed, reporting
+  where it is**. Under the root, under `.claude/skills/`, under
+  `.squadbase/skills/` — it makes no difference, so **re-running never creates a
+  second copy**, and an agent no longer has to know the candidate locations.
+  - `--force` rewrites the copies **where they were found** (an explicit `--dir`
+    still wins as the destination), so refreshing placed copies doesn't require
+    remembering the `--dir` you used originally.
+  - `vantage add skill` with no name is now a listing command: it prints the
+    bundled skills and where each one sits, and writes nothing.
+  - The bundled `AGENTS.md` drops its `ls`-the-usual-places routine in favour of
+    letting the CLI find them (a placed `AGENTS.md` is synced by `vantage upgrade`).
+
+### Fixed
+
+- **[`EChart`](parts/echart) could miss a CSS update** — token
+  changes were only watched through attributes on `<html>` / `<body>`, so a
+  change that **only rewrites the injected `<style>`** (editing `styles.css` with
+  the dev server running, applying a theme preset, …) left the chart painted in
+  the previous colours while the DOM tokens were already new. A reload fixed it,
+  which made it read as "the preset didn't apply". Stylesheet swaps are now
+  watched as well, and the chart repaints **only when the token values actually
+  change**.
+
 ## v0.2.1
 
 Charts now follow the theme tokens, and `Select` works out the value-to-label

package/docs/en/cli-reference.md

@@ -13,7 +13,7 @@
 | `vantage preview` | Run the production build locally (fullstack default `:4173`; spa via Vite preview) |
 | `vantage check` | Static checks (routes, boundaries, forbidden files). Exit 1 on error |
 | `vantage routes` | Print the page + API URL map |
-| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` takes `--dir` for the destination) |
+| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` scans for copies already placed and skips them, `--dir` picks the destination) |
 | `vantage docs [name]` | Show the bundled guide and component reference |
 | `vantage search <query>` | Search that same reference in full text (natural language or `--regex`) |
 | `vantage doctor` | Diagnose environment / installation health |

package/docs/en/parts/echart.md

@@ -27,8 +27,10 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 
 By default the theme's `--chart-1` through `--chart-5` become the series colours. ECharts can't read
 CSS variables *while painting*, but `EChart` resolves the tokens once at init with
-`getComputedStyle` and passes them in as an ECharts theme. It watches for the `.dark` class going on
-and off, and re-reads the tokens when it changes.
+`getComputedStyle` and passes them in as an ECharts theme. It watches for anything that can change
+those tokens and re-reads them when the values actually move — the `.dark` class going on and off,
+and **stylesheet swaps** too (editing `styles.css` with the dev server running, applying a theme
+preset, …).
 
 To give series their own colours, set `option.color` (or `series[].itemStyle.color`). Your option
 wins over the theme, so **axes, legend and tooltip keep following the tokens**.

package/docs/ja/agent-skills.md

@@ -22,12 +22,29 @@ Skill のソースは `@squadbase/vantage` パッケージに同梱されてい
 対象アプリにコピーします。配置先は既定で**プロジェクトルート直下**で、`--dir` で変えられます。
 
 ```bash
-vantage add skill --all                       # 同梱スキルをすべて、ルート直下に配置
+vantage add skill                             # 一覧と配置場所を表示するだけ(何も書かない)
+vantage add skill --all                       # 未配置のものを、ルート直下に配置
 vantage add skill vantage-app                 # 名前を指定して1つだけ配置
 vantage add skill --all --dir .claude/skills  # Claude Code が読む場所に配置
-vantage add skill vantage-app --force         # 既存を上書き
+vantage add skill --all --force               # 配置済みのコピーをその場で最新に更新
 ```
 
+**配置先は決め打ちではなく、走査して見つけます。** `add skill` はまずプロジェクト内
+(`node_modules` などを除く)を走査し、**既に配置されている skill はスキップして場所を報告**
+します。ルート直下でも `.claude/skills/` でも `.squadbase/skills/` でも同じで、**再実行しても
+二重に配置されません**。名前を省いて実行すると、一覧と配置場所だけが出ます:
+
+```text
+$ vantage add skill
+Bundled skills:
+  vantage-add-feature  .claude/skills/vantage-add-feature/
+  vantage-app          .claude/skills/vantage-app/
+  vantage-pitfalls     not placed
+```
+
+`--force` を付けると、**見つかった場所をそのまま**新しい内容で書き換えます(`--dir` を明示した
+ときは、そちらが配置先として優先されます)。
+
 `--dir` のパスはプロジェクトルートからの相対で解決されます（絶対パスも可）。Claude Code に
 自動認識させるなら `.claude/skills/` に置きます:
 
@@ -54,8 +71,8 @@ Skill の手順を読み込んで実行します。他のエージェントに
 
 - **source-of-truth はパッケージ内**にあります。Skill はフレームワークのバージョンと一緒に
   配布・更新されるため、`@squadbase/vantage` を上げれば最新の手順が手に入ります。配置済みの
-  コピーを更新したいときは、配置したときと同じ `--dir` を付けて
-  `vantage add skill --all --force` を実行します。
+  コピーを更新したいときは `vantage add skill --all --force` を実行します(置き場所は走査して
+  見つけるので、`--dir` を覚えておく必要はありません)。
 - **Squadbase テンプレートには配置済み**です。テンプレートから作ったアプリには、最初から
   `.claude/skills/` が入っています。手で作ったアプリには `vantage add skill` で足してください。
 

package/docs/ja/changelog.md

@@ -8,6 +8,34 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.2.2
+
+`vantage add skill` が配置先を走査するようになり、チャートがスタイルシートの差し替えにも
+追従するようになりました。どちらも後方互換です。
+
+### 変更
+
+- **`vantage add skill` が配置済みの Skill を探してからコピーします** ― プロジェクト内を
+  走査して `<skill>/SKILL.md` を探し、**既にあればスキップして場所を報告**します。ルート直下
+  でも `.claude/skills/` でも `.squadbase/skills/` でも同じなので、**再実行しても二重に配置
+  されません**。エージェント側が置き場所の候補を覚えておく必要がなくなります。
+  - `--force` は**見つかった場所をその場で**書き換えます(`--dir` を明示したときは、そちらが
+    配置先として優先されます)。配置済みコピーの更新に、前回と同じ `--dir` を思い出す必要は
+    ありません。
+  - 名前を省いた `vantage add skill` は、**一覧と配置場所を出すだけ**の表示コマンドに
+    なりました(何も書き込まず exit 0)。
+  - 同梱の `AGENTS.md` も更新し、置き場所を `ls` で当てにいく手順を「CLI が探す」に
+    置き換えました(配置済みの `AGENTS.md` は `vantage upgrade` で同期されます)。
+
+### 修正
+
+- **[`EChart`](parts/echart) が CSS の更新に追従しない場合がありました** ―
+  トークンの変化を `html` / `body` の属性でしか見ていなかったため、**注入済みの `<style>` の
+  中身だけが差し替わる経路**(開発中の `styles.css` の書き換え、テーマプリセットの適用など)で
+  DOM のトークンは新しいのにチャートだけ前の色のまま残っていました(リロードで直るため
+  「プリセットが効いていない」と誤解しやすい状態でした)。スタイルシートの差し替えも監視
+  対象になり、**トークンの値が実際に変わったときだけ**描き直します。
+
 ## v0.2.1
 
 チャートをテーマトークンに追従させ、`Select` の値とラベルの対応を Vantage 側で組むように

package/docs/ja/cli-reference.md

@@ -13,7 +13,7 @@
 | `vantage preview` | 本番ビルドをローカルで起動（fullstack は既定 `:4173`、spa は Vite プレビュー） |
 | `vantage check` | 静的検査（ルート・境界・禁止ファイル）。エラーがあれば exit 1 |
 | `vantage routes` | ページ + API の URL マップを表示 |
-| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は `--dir` で配置先を指定） |
+| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は配置済みを走査してスキップ・`--dir` で配置先を指定） |
 | `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
 | `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
 | `vantage doctor` | 環境・インストールの健全性を診断 |

package/docs/ja/parts/echart.md

@@ -27,8 +27,9 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 
 既定ではテーマの `--chart-1` 〜 `--chart-5` がそのまま系列色になります。ECharts は**描画中**には
 CSS 変数を読めませんが、`EChart` は init のタイミングで `getComputedStyle` からトークンの実値を
-解決し、ECharts のテーマとして渡しています。`.dark` の付け外しを見張っていて、切り替われば
-読み直します。
+解決し、ECharts のテーマとして渡しています。**トークンが変わりうる操作は見張っていて**、値が
+実際に変わったときだけ読み直します ― `.dark` の付け外しだけでなく、**スタイルシートの差し替え**
+(開発中に `styles.css` を書き換えた・テーマプリセットを当てた、など)も拾います。
 
 系列に固有の色を当てたいときは `option.color`(または `series[].itemStyle.color`)で上書きします。
 option はテーマより優先されるので、**軸・凡例・ツールチップのトークン追従は残ります**。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",

package/skills/vantage-app/SKILL.md

@@ -57,7 +57,7 @@ API export・env 誤用)はユーザーコードを実行しないので速く
 vantage routes     # 既にあるページと API の URL マップ
 vantage check      # いま壊れていないか(これから出すエラーと切り分ける)
 ls server/         # あれば fullstack モード。無ければ SPA
-ls .claude/skills  # 配置済みの skill(このファイルの仲間)
+vantage add skill  # 配置済みの skill(このファイルの仲間)と、その場所
 ```
 
 ## Step 2 — ルートを決める

package/skills/vantage-pitfalls/SKILL.md

@@ -37,8 +37,9 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
-系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれ、
-ライト / ダークの切り替えにも追従する(init 時にトークンの実値を解決している)。
+系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる
+(init 時にトークンの実値を解決している)。ライト / ダークの切り替えにも、`styles.css` の
+書き換えやテーマプリセットの適用にも追従する。
 
 - **`theme` プロップを渡すと追従は完全に止まる。** 系列の色だけ変えたいなら `option.color` を
   使う ― option はテーマより優先されるので、軸まわりの追従は残る。

package/templates/AGENTS.md

@@ -318,18 +318,20 @@ pnpm preview   # 本番ビルドをローカル実行
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
 
-**まず、このアプリに配置済みかを探す。** 手順書の本体は SKILL.md というファイルで、置き場所は
-アプリによって違う:
+手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
+`.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**
 
 ```bash
-ls .claude/skills          # よくある置き場所
-ls -d vantage-*            # ルート直下に置くのが既定
+vantage add skill          # 同梱 skill の一覧と、それぞれの配置場所
 ```
 
-見つかったらその `SKILL.md` を読む(`vantage add skill` を再実行する必要はない)。**無いときだけ**
-配置する ― 一覧は名前を省いて実行すると出る:
+配置済みならその場所が出るので、その `SKILL.md` を読む。`not placed` のものだけ配置する:
 
 ```bash
-vantage add skill                              # 同梱されている skill 名の一覧
-vantage add skill --all --dir .claude/skills   # 配置(--dir を省くとルート直下)
+vantage add skill --all                        # 配置済みはスキップ(場所を報告するだけ)
+vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定はルート直下)
 ```
+
+`add skill` はプロジェクト内を走査してから動くので、**再実行しても二重に配置されない**。
+配置済みのコピーを新しいバージョンに更新したいときだけ `--force` を付ける(見つかった場所を
+そのまま書き換える)。