@squadbase/vantage 0.5.0 → 0.5.1

package/README.md

@@ -7,7 +7,7 @@ You write `index.tsx`. Vantage owns routing, React, TanStack Query, Tailwind v4,
 the UI kit, the dev server, the optional API server, and the build. There is no
 config file.
 
-> **Status: prototype (v0.5.0).** APIs may still change between releases.
+> **Status: prototype (v0.5.1).** APIs may still change between releases.
 
 ## Install
 

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.5.0";
+declare const VERSION = "0.5.1";
 
 export { VERSION };

package/dist/index.js

@@ -6,7 +6,7 @@ function definePage(config) {
 }
 
 // src/index.ts
-var VERSION = "0.5.0";
+var VERSION = "0.5.1";
 
 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.5.0\"\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.5.1\"\n"]}

package/docs/en/changelog.md

@@ -9,6 +9,34 @@ 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.5.1
+
+Fixes `dark:` utilities not being wired to the same switch as the theme tokens.
+Anything on `^0.5.0` picks this up as-is.
+
+### Fixed
+
+- **`dark:` now follows the `.dark` class, not the OS setting.** Tailwind's stock
+  `dark:` is `@media (prefers-color-scheme: dark)`, but Vantage's tokens only flip
+  when an ancestor carries `.dark` / `[data-theme="dark"]`. **In a browser set to
+  OS dark mode** that split the theme in two — background and text tokens stayed
+  light while every `dark:` class fired. Text vanished on white cards, badges
+  inverted on their own, and so on.
+
+  ```tsx
+  // 0.5.0: on an OS-dark browser, this text disappeared against the white card
+  <div className="text-slate-900 dark:text-slate-100">{name}</div>
+  ```
+
+  `theme.css` now binds `dark:` to the same class as the tokens. **Unless you add
+  `.dark` / `[data-theme="dark"]` yourself, the app always renders light**
+  (→ [UI and theming](ui-and-theming)). If your app meant to follow the OS
+  setting, set the class on your root element explicitly.
+
+- **`color-scheme` is now declared** — browser-owned UI (scrollbars, `<select>`
+  popups, autofill) no longer goes dark on an OS-dark machine while the app itself
+  stays light.
+
 ## v0.5.0
 
 Browser-to-terminal forwarding now runs on Vite's native mechanism. Which levels

package/docs/en/roadmap.md

@@ -0,0 +1,199 @@
+# Roadmap
+
+> Where Vantage is heading — ideas under consideration for giving agents eyes and memory, plus what we deliberately will not do.
+
+Where Vantage is heading. For what already works, see the [changelog](changelog);
+for what you can write today, see the guides.
+
+> [!WARNING]
+> Nothing on this page is implemented yet. The order and the contents will change, and
+> some of it will be dropped entirely. **Do not write apps that depend on anything here.**
+
+## The premise — who is this framework for?
+
+Vantage treats **AI coding agents as first-class citizens**. Being pleasant for humans
+to read matters less than letting an agent **write it without mistakes and verify it on
+its own**. That is why config files are banned, why the framework owns the UI kit and
+the data layer, and why `vantage docs` / `vantage search` live in the CLI —
+**the CLI is the agent's interface, and conventions remove the room for judgment.**
+
+Seen from that angle, today's Vantage supports agents well in two places:
+
+- **Before writing** — `vantage docs` / `vantage search` / `vantage add skill` / `AGENTS.md`
+- **Verifying statically** — `vantage check` / `vantage routes`
+
+And there is one large gap.
+
+> **An agent cannot see the screen it just wrote.**
+
+Browser-to-terminal forwarding in `vantage dev` (`console.warn` / `console.error` and
+uncaught errors) is the first small window into that gap. Most of the ideas below exist
+to close it.
+
+## In design
+
+### Element inspector — from the screen to the agent
+
+Hover and click an element in the browser, then tell the agent "fix **this**". A staple
+of vibe-coding tools, but here it belongs to the **framework** rather than to each app.
+
+Three parts:
+
+- **Inject source locations into JSX in development only** —
+  `data-vtg="src/sales/index.tsx:42:7"` plus the component name. Vantage owns its UI kit,
+  and most of it spreads `{...props}` straight onto the DOM, so an attribute placed on
+  something like `<DataTable />` still reaches a real DOM node.
+- **A development-only overlay** that outlines the element, labels it, and emits the selection.
+- **`vantage select`** so the agent picks the selection up from the CLI, with `--json` and
+  a `--wait` that blocks until something is selected.
+
+Production builds drop both the attributes and the overlay **entirely** — leaving source
+paths in a bundle is a straight information leak.
+
+For tools that embed the preview in an iframe, such as Squadbase Editor, the selection is
+also posted over `postMessage`, and the overlay itself can be taken over by the host tool.
+Vantage owns the correctness of the position data and a minimal default UI; the polished
+experience belongs to the tool.
+
+## Under consideration — giving agents eyes
+
+### `vantage snap` — a structured snapshot of a page
+
+Render each route headlessly and return **structured text rather than an image**.
+
+```jsonc
+{
+  "route": "/sales",
+  "state": "ready",                    // loading | ready | error | empty
+  "regions": [
+    { "type": "kpi",   "labels": ["Revenue", "MoM"], "values": ["$12.4M", "+8.2%"] },
+    { "type": "chart", "component": "EChart",   "series": ["actual", "target"], "points": 12 },
+    { "type": "table", "component": "DataTable", "columns": ["date", "store", "amount"], "rows": 0 }
+  ],
+  "console": [{ "level": "warn", "text": "…" }],
+  "network": [{ "url": "/api/sales", "status": 500 }]
+}
+```
+
+For an agent this is orders of magnitude more readable than a screenshot. "The table has
+zero rows" and "the API returned 500" are exactly the failures **nobody notices until a
+human pastes a screenshot**.
+
+Those `regions` can carry meaning only because Vantage owns the UI kit, the routing, and
+the data layer. A general-purpose browser automation tool cannot produce this granularity,
+which is why we think this is the strongest bet on the list.
+
+### `vantage check --runtime` — diagnostics that need a render
+
+Today's [diagnostics](cli-reference) only read source. This would put the failures that
+require an actual render behind the same command and the same exit code.
+
+- A query stuck pending, so the page never leaves its loading state
+- Fetching succeeded but the table or chart is empty
+- An API returned 4xx / 5xx during the render
+- Unhandled promise rejections
+- An element overflowing its parent
+
+The goal is to **close the agent's self-verification loop with an exit code** — one line
+that says: if `vantage check` passes, it is safe to ship.
+
+### `vantage dev --agent` — a structured event stream
+
+The dev server would emit HMR results, render errors, API responses, and slow queries as
+NDJSON on a separate channel. Human-facing terminal output stays as it is, while an agent
+tails the stream and **learns it broke something the moment it edits**. A natural extension
+of today's console forwarding.
+
+## Under consideration — giving agents memory
+
+### An `intent` field on `definePage`
+
+Let the framework hold **what a page is for** as structure.
+
+```tsx
+export const page = definePage({
+  title: "Sales dashboard",
+  intent: "Spot stores missing their target by looking at daily revenue per store",
+});
+```
+
+Comments get lost as code is rewritten; this shows up in `vantage routes` and lands in the
+manifest. The readers are "yourself thirty turns from now" and "the next agent to pick this
+up". It is the per-page version of the same idea behind `AGENTS.md` and Agent Skills:
+**the framework decides where memory lives.**
+
+### `vantage diff` — diffing the app, not the code
+
+```text
+routes    + /reports/monthly    - /legacy
+api       ~ GET /api/sales      (POST is gone)
+render    /sales  table columns 5 → 4  ("owner" disappeared)
+bundle    +11.2 MB
+```
+
+Agents systematically miss the **side effects** of their own edits. This confronts them with
+the difference between the change they intended and the change that happened.
+
+### `vantage explain <route|file>`
+
+Documentation in reverse, for an agent inheriting an existing app: the route, the components
+in use, the APIs it calls, the environment variables it depends on, and the parent layouts,
+on one screen. An extension of `vantage routes --detail`, aimed at **a granularity that
+replaces reading the source** and cuts context consumption sharply.
+
+## Under consideration — preventing the mistake
+
+### Turn errors into entry points to the docs
+
+Vantage knows its own stack inside out — TanStack Query, Base UI, ECharts, Hono. When it
+forwards a browser error to the terminal, it should be able to **append the next move**.
+
+```text
+[console.error] Cannot read properties of undefined (reading 'map')
+ > src/sales/index.tsx:42
+   ↳ data from useApiQuery is undefined on the first render. Use `data?.map`
+     or branch on isLoading → vantage docs data-fetching
+```
+
+Agents stumble hardest at "what should I even search for", so the error itself should pull
+up the documentation.
+
+### Absorb common mistakes instead of diagnosing them
+
+A generalization of how the UI kit already absorbs Base UI's `Select` quirks. **A diagnostic
+that fires often is a candidate for being made to just work.** We want to treat "how often
+agents get this wrong" as a metric for improving the framework.
+
+### `vantage check --budget`
+
+Fail the build on bundle-size or first-render regressions. Agents add heavy dependencies
+without hesitation — a single Markdown renderer can add more than 10 MB of output. This turns
+the unease a human would feel into a threshold a machine can read.
+
+### Scaffolding from the shape of the data
+
+Hand it an API response or a SQL result and get back a page skeleton suited to that shape:
+a line chart for time series, a table plus KPIs for category × value, and so on. Agents redo
+this judgment from scratch every time; the conventional answers belong in the framework.
+
+## What we deliberately will not do
+
+What is *not* on a roadmap matters just as much, so here is the current position.
+
+- **Config files.** There will be no `vantage.config`. When something seems to need
+  configuration, we first ask whether a convention or a flag can solve it. Room for judgment
+  is a liability for an agent.
+- **A swappable stack.** React, the router, the data layer, and the UI kit are fixed by
+  Vantage. The moment swapping is allowed, the docs, the skills, and the diagnostics all have
+  to assume they do not know what you are using — and nearly every idea above stops working.
+- **Replacing the `QueryClient` wholesale.** Customization happens per query (see
+  [data fetching](data-fetching)).
+- **Becoming a general-purpose application framework.** Vantage is a framework for
+  **dashboards**. Rather than broadening the scope, we would rather step on every landmine
+  dashboards have to offer.
+
+## Feedback
+
+We would rather prioritize the list above from real friction. If you hit a spot where the
+agent always gets it wrong, or where you were stuck because something was not discoverable,
+please tell us.

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

@@ -78,6 +78,25 @@ and `--sidebar-*` for the sidebar. Changing `--chart-*` also changes
 [`EChart`](parts/echart)'s palette — charts build their theme by reading those CSS
 variables directly.
 
+## Dark mode is opt-in
+
+The dark tokens apply only when an ancestor carries `.dark` or `[data-theme="dark"]`. Vantage
+**does not read the OS/browser setting (`prefers-color-scheme`)** — a dashboard reads better when it
+doesn't flip with whatever it happens to be embedded in, so the switch stays with the app.
+
+`dark:` utilities are wired to the same switch (`theme.css` declares it via `@custom-variant dark`).
+Without a `.dark` ancestor no `dark:` utility applies, so the theme can't split in two — light tokens
+under dark-mode utilities.
+
+```tsx
+// With no `.dark` ancestor, the second class does nothing
+<div className="text-foreground dark:text-slate-100" />
+```
+
+> [!NOTE]
+> Prefer the semantic tokens (`text-foreground`, `text-muted-foreground`, `bg-card`) over the raw
+> Tailwind palette (`text-slate-900`). Written with tokens, you rarely need a `dark:` pair at all.
+
 ## When you want to edit the source: `vantage add`
 
 To make a component's internals your own, copy an editable source into `components/`.

package/docs/index.json

@@ -123,6 +123,17 @@
       "order": 10,
       "searchable": false
     },
+    {
+      "slug": "roadmap",
+      "lang": "ja",
+      "section": "guide",
+      "sectionTitle": "ガイド",
+      "title": "ロードマップ",
+      "description": "Vantage がこれから向かう方向。エージェントに「目」と「記憶」を与えるための検討中のアイデアと、意図的にやらないこと。",
+      "file": "ja/roadmap.md",
+      "order": 11,
+      "searchable": false
+    },
     {
       "slug": "components",
       "lang": "ja",
@@ -804,6 +815,17 @@
       "order": 10,
       "searchable": false
     },
+    {
+      "slug": "roadmap",
+      "lang": "en",
+      "section": "guide",
+      "sectionTitle": "Guide",
+      "title": "Roadmap",
+      "description": "Where Vantage is heading — ideas under consideration for giving agents eyes and memory, plus what we deliberately will not do.",
+      "file": "en/roadmap.md",
+      "order": 11,
+      "searchable": false
+    },
     {
       "slug": "components",
       "lang": "en",

package/docs/ja/changelog.md

@@ -8,6 +8,34 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.5.1
+
+`dark:` ユーティリティがテーマトークンと同じスイッチに繋がっていなかった不具合の修正です。
+`^0.5.0` を指定していればそのまま入ります。
+
+### 修正
+
+- **`dark:` が OS の設定ではなく `.dark` クラスに従うようになりました。** Tailwind の既定の
+  `dark:` は `@media (prefers-color-scheme: dark)` ですが、Vantage のトークンは祖先の
+  `.dark` / `[data-theme="dark"]` でしか切り替わりません。そのため **OS がダークのブラウザ**では
+  テーマが二つに割れていました ― 背景・文字色のトークンはライトのまま、`dark:` の付いた
+  クラスだけが全部効いてしまう。白いカードの上で `dark:text-slate-100` の文字が消える、
+  バッジだけ黒地に反転する、といった症状が出ます。
+
+  ```tsx
+  // 0.5.0: OS がダークだと、白いカードの上でこの文字が見えなくなっていた
+  <div className="text-slate-900 dark:text-slate-100">{name}</div>
+  ```
+
+  `theme.css` で `dark:` をトークンと同じクラスに繋ぎ直しました。**`.dark` /
+  `[data-theme="dark"]` を自分で付けない限り、アプリは常にライトで描かれます**
+  (→ [UI とテーマ](ui-and-theming))。OS の設定に追従させていたつもりのアプリは、
+  ルート要素へ明示的にクラスを付けてください。
+
+- **`color-scheme` を宣言するようになりました** ― スクロールバー、`<select>` のポップアップ、
+  オートフィルといったブラウザ側の UI が、アプリはライトなのに OS 設定でダークになる、という
+  ちぐはぐが解消します。
+
 ## v0.5.0
 
 ブラウザから開発ターミナルへの転送を Vite ネイティブの仕組みに置き換えました。転送される

package/docs/ja/roadmap.md

@@ -0,0 +1,196 @@
+# ロードマップ
+
+> Vantage がこれから向かう方向。エージェントに「目」と「記憶」を与えるための検討中のアイデアと、意図的にやらないこと。
+
+Vantage がこれから向かおうとしている方向をまとめたページです。**すでに動くもの**については
+[変更履歴](changelog)を、いま書けることについては各ガイドを参照してください。
+
+> [!WARNING]
+> ここに書かれているものは**まだ実装されていません**。順序も内容も変わりますし、途中で丸ごと
+> 取りやめることもあります。**このページの機能を前提にアプリを書かないでください。**
+
+## 前提 ― 誰のためのフレームワークか
+
+Vantage は **AI コーディングエージェントを一級市民**として設計されています。人間が読みやすいこと
+より、エージェントが**間違えずに書けること・自分で検証できること**を優先します。設定ファイルを
+禁止しているのも、UI キットとデータ層をフレームワークが所有しているのも、`vantage docs` /
+`vantage search` が CLI にあるのも、すべて同じ理由です ―
+**エージェントの窓口は CLI であり、判断の余地は規約で潰す。**
+
+この視点で今の Vantage を眺めると、支援が厚いのは 2 箇所です。
+
+- **書く前** ― `vantage docs` / `vantage search` / `vantage add skill` / `AGENTS.md`
+- **静的に検証する** ― `vantage check` / `vantage routes`
+
+そして、大きな空白が 1 つあります。
+
+> **エージェントは、自分が書いた画面を見られない。**
+
+`vantage dev` のブラウザ → ターミナル転送（`console.warn` / `console.error` / 未捕捉エラー）は、
+その穴に開いた最初の小さな窓です。以下のアイデアは、ほとんどがこの穴を埋めるためのものです。
+
+## 設計中
+
+### 要素インスペクタ ― 画面からエージェントへ
+
+ブラウザ上の要素をホバー・クリックで選び、「**これ**を直して」とエージェントに渡す仕組み。
+バイブコーディングツールでは定番の体験ですが、これをアプリ側の実装ではなく
+**フレームワークの機能**として持ちます。
+
+構成は 3 つです。
+
+- **開発時だけ JSX にソース位置を注入する** ― `data-vtg="src/sales/index.tsx:42:7"` と
+  コンポーネント名。Vantage は UI キットを自分で所有していて、その大半が `{...props}` を
+  そのまま DOM へ渡すため、`<DataTable />` のような要素に付けた属性も実際の DOM まで届きます。
+- **開発時だけのオーバーレイ** ― 要素の輪郭とラベルを描き、選択結果を送出する。
+- **`vantage select`** ― 選択されたものをエージェントが CLI から受け取る。
+  `--json` と、選択されるまで待つ `--wait`。
+
+本番ビルドでは属性もオーバーレイも**完全に落とします**（ソースパスがバンドルに残るのは
+情報漏洩そのものなので）。
+
+Squadbase Editor のようにプレビューを iframe で埋め込むツール向けには、選択結果を
+`postMessage` でも流し、オーバーレイの見た目自体をツール側が乗っ取れるようにする方針です。
+Vantage が持つのは「位置情報の正しさ」と最小限の既定 UI までで、体験の作り込みはツール側に
+譲ります。
+
+## 検討中 ― エージェントに「目」を与える
+
+### `vantage snap` ― ページの構造化スナップショット
+
+各ルートをヘッドレスで描画し、**画像ではなく構造化テキスト**で返すコマンド。
+
+```jsonc
+{
+  "route": "/sales",
+  "state": "ready",                    // loading | ready | error | empty
+  "regions": [
+    { "type": "kpi",   "labels": ["今月の売上", "前月比"], "values": ["¥12.4M", "+8.2%"] },
+    { "type": "chart", "component": "EChart",   "series": ["売上", "目標"], "points": 12 },
+    { "type": "table", "component": "DataTable", "columns": ["日付", "店舗", "金額"], "rows": 0 }
+  ],
+  "console": [{ "level": "warn", "text": "…" }],
+  "network": [{ "url": "/api/sales", "status": 500 }]
+}
+```
+
+エージェントにとっては、スクリーンショットの画像よりこの形のほうが桁違いに読めます。
+「表が 0 行」「API が 500 を返している」は、**人間がスクリーンショットを貼るまで誰も気づかない**
+種類の失敗です。
+
+`regions` に意味づけができるのは、Vantage が UI キット・ルーティング・データ層をすべて
+所有しているからです。汎用のブラウザ自動化ツールには出せない粒度で、ここが最大の勝ち筋だと
+考えています。
+
+### `vantage check --runtime` ― 描画して初めてわかる診断
+
+いまの [診断](cli-reference) はソースを読むだけの静的なものです。実際に描画しないと
+分からない失敗を、同じコマンド・同じ終了コードに載せます。
+
+- クエリが pending のまま抜けず、ローディング表示から戻らない
+- データ取得は成功しているのに表やチャートが空
+- 描画中に叩いた API が 4xx / 5xx を返した
+- 未処理の Promise リジェクション
+- 要素が親の幅をはみ出している
+
+狙いは「**エージェントの自己検証ループが終了コードで閉じる**」ことです。`vantage check` が
+通れば出荷してよい、という一本の線を引きたい。
+
+### `vantage dev --agent` ― 構造化イベントストリーム
+
+開発サーバーが、HMR の成否・描画エラー・API のレスポンス・遅いクエリを NDJSON で別チャネルへ
+出す案。人間向けのターミナル出力は今のままにして、エージェントは追記を読み続けることで
+**編集した直後に壊れたことを知れる**ようにします。いまのコンソール転送の自然な延長線です。
+
+## 検討中 ― エージェントに「記憶」を与える
+
+### `definePage` の `intent`
+
+そのページが**何のためにあるか**をフレームワークが構造として持つ案。
+
+```tsx
+export const page = definePage({
+  title: "売上ダッシュボード",
+  intent: "店舗別の日次売上を見て、目標未達の店舗を早く見つける",
+});
+```
+
+コメントは書き換えの過程で消えますが、これは `vantage routes` に出てマニフェストに載る
+**構造**です。読者は「30 ターン後の自分」や「引き継いだ別のエージェント」。
+`AGENTS.md` や Agent Skills と同じ「**フレームワークが記憶の置き場所を規定する**」という
+考え方の、ページ単位版にあたります。
+
+### `vantage diff` ― コードの差分ではなくアプリの差分
+
+```text
+routes    + /reports/monthly    - /legacy
+api       ~ GET /api/sales      (POST が消えた)
+render    /sales  表の列 5 → 4  ("担当者" が消えた)
+bundle    +11.2 MB
+```
+
+エージェントは自分の変更の**副作用**を系統的に見落とします。「意図した変更」と「実際に起きた
+変更」の差を突きつけるためのコマンドです。
+
+### `vantage explain <route|file>`
+
+既存のアプリを引き継いだエージェント向けの、逆向きのドキュメント。そのページのルート・使って
+いるコンポーネント・叩いている API・依存している環境変数・親レイアウトを 1 画面にまとめます。
+`vantage routes --detail` の延長ですが、狙いは「**ソースを読む代わりになる粒度**」で、
+コンテキストの消費を大きく減らすことです。
+
+## 検討中 ― そもそも間違えさせない
+
+### エラーをドキュメントへの入口にする
+
+Vantage は自分のスタック（TanStack Query・Base UI・ECharts・Hono）を全部知っています。
+ブラウザのエラーをターミナルへ転送するときに、**次の一手を添える**ことができるはずです。
+
+```text
+[console.error] Cannot read properties of undefined (reading 'map')
+ > src/sales/index.tsx:42
+   ↳ useApiQuery の data は初回 undefined です。`data?.map` にするか
+     isLoading で分岐してください → vantage docs data-fetching
+```
+
+エージェントが最もつまずくのは「何を検索すればいいか分からない」場面なので、
+**エラーが自動的にドキュメントを引く**形にします。
+
+### 「よく間違える」を診断ではなく吸収で潰す
+
+Base UI の `Select` の癖を UI キット側で吸収しているのと同じ方針の一般化です。
+**診断が頻繁に鳴るパターンは、診断ではなく「そのまま書いても動く」ようにする候補**と考えます。
+エージェントが間違えた回数そのものを、フレームワークの改善指標として扱いたい。
+
+### `vantage check --budget`
+
+バンドルサイズや初期描画の回帰でビルドを止める案。エージェントは重い依存を平気で追加します
+（Markdown レンダラを 1 つ足しただけで出力が 10 MB 以上増えることがあります）。人間なら気づく
+違和感を、機械が読める閾値に落とします。
+
+### データの形から骨格を作る
+
+API のレスポンスや SQL の結果を渡すと、その形に合った可視化の骨格を出す案
+（時系列なら折れ線、カテゴリ × 数値なら表と KPI、など）。エージェントは毎回この判断を
+ゼロからやり直しているので、定石はフレームワークが持つべきだと考えています。
+
+## 意図的にやらないこと
+
+ロードマップに載らないことも同じくらい重要なので、現時点の方針を書いておきます。
+
+- **設定ファイルの導入** ― `vantage.config` は作りません。設定を足したくなったら、それは
+  規約かフラグで解けないかをまず疑います。判断の余地はエージェントにとって負債です。
+- **スタックの差し替えを可能にすること** ― React・ルーター・データ層・UI キットは
+  Vantage が固定します。差し替えを許した瞬間、ドキュメントも Skill も診断も「相手が何を
+  使っているか分からない」前提になり、上に挙げたアイデアはほぼ全部成立しなくなります。
+- **`QueryClient` の丸ごと差し替え** ― カスタマイズの手段はクエリ単位の上書きです
+  （[データ取得](data-fetching)を参照）。
+- **汎用のアプリケーションフレームワーク化** ― Vantage は**ダッシュボード**のための
+  フレームワークです。用途を広げるより、ダッシュボードで踏む地雷を全部踏み抜いておくことに
+  投資します。
+
+## フィードバック
+
+上のアイデアの優先順位は、実際に詰まった場所で決めたいと考えています。使っていて
+「エージェントがここで必ず間違える」「これが分からず手が止まった」という箇所があれば、
+ぜひ教えてください。

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

@@ -78,6 +78,26 @@ import { cn } from "@squadbase/vantage/ui";
 [`EChart`](parts/echart) の配色も一緒に変わります。チャートは CSS 変数を実際に読み取って
 テーマを組み立てるためです。
 
+## ダークモードは opt-in
+
+ダークのトークンが効くのは、祖先に `.dark` か `[data-theme="dark"]` が付いているときだけです。
+**OS やブラウザの設定（`prefers-color-scheme`）は見ません** ― ダッシュボードは埋め込み先の
+明暗に勝手に追従しないほうが読めるため、切り替えはアプリ側の明示的な指定に任せています。
+
+`dark:` ユーティリティも同じスイッチに繋がっています（`theme.css` が
+`@custom-variant dark` でそう定義しています）。`.dark` が無ければ `dark:` は一切効かないので、
+トークンだけライトで `dark:` だけダーク、という食い違いは起きません。
+
+```tsx
+// `.dark` が付いていなければ、下段のクラスは効かない
+<div className="text-foreground dark:text-slate-100" />
+```
+
+> [!NOTE]
+> 色は素の Tailwind パレット（`text-slate-900` など）ではなく、
+> セマンティックトークン（`text-foreground` / `text-muted-foreground` / `bg-card`）で書くのが
+> おすすめです。トークンで書けば `dark:` を並べる必要がそもそも無くなります。
+
 ## ソースを編集したいとき: `vantage add`
 
 コンポーネントの中身を自分のものにしたいときは、編集可能なソースを `components/` にコピーします。

package/package.json

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

package/skills/vantage-pitfalls/SKILL.md

@@ -35,6 +35,28 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
 
+## 配色:素のパレット + `dark:` ではなく、セマンティックトークンで書く
+
+色は `text-foreground` / `text-muted-foreground` / `bg-card` / `border-border` などの
+トークンで書く。トークンはライト / ダークの両方を持っているので、`dark:` を並べる必要が無い。
+
+`text-slate-900 dark:text-slate-100` のような素の Tailwind パレット + `dark:` の組は、
+**トークンで塗られた周囲と食い違う**。ダークトークンが効くのは祖先に `.dark` /
+`[data-theme="dark"]` が付いているときだけで、`dark:` ユーティリティも同じスイッチに
+繋がっている(`theme.css` の `@custom-variant dark`)。つまり自分でクラスを付けない限り
+アプリは常にライトで動くのに、素のパレットを使うとその 1 か所だけ手動で両モードを
+管理することになる。
+
+```tsx
+// ✗ 手動で 2 モードを管理することになる
+<div className="font-medium text-slate-900 dark:text-slate-100">{name}</div>
+// ✓ トークンなら 1 つで済む
+<div className="font-medium text-foreground">{name}</div>
+```
+
+`--muted` / `--accent` / `--secondary` / `--border` は**背景・境界用**で、ライトではほぼ白。
+文字色に使うと読めなくなる ― 弱い文字色は `text-muted-foreground`。
+
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる

package/templates/AGENTS.md

@@ -36,6 +36,11 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **クライアントに届く env は `PUBLIC_` 接頭辞のものだけ。** `import.meta.env.PUBLIC_FOO`。
   それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。シークレットは
   `ApiContext.env`(server/ 内)にだけ届く。
+- **色はセマンティックトークンで書く。** `text-foreground`・`text-muted-foreground`・`bg-card`・
+  `border-border`。トークンがライト / ダークの両方を持つので `dark:` を並べる必要が無い。
+  素のパレット + `dark:`(`text-slate-900 dark:text-slate-100`)を混ぜると、その 1 か所だけ
+  手動で 2 モードを管理することになる(→「ダークモードは opt-in」)。`--muted`・`--accent`・
+  `--secondary`・`--border` は背景・境界用で、文字色に使うと読めない。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
   コマンド、または `vantage upgrade` で再生成される。
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
@@ -318,6 +323,16 @@ const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST
   `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"` を
+自分で付ける。
+
 ## ドキュメントを引く(`vantage docs` / `vantage search`)
 
 ```bash

package/theme.css

@@ -12,6 +12,12 @@
    on top — charts need distinguishable colours, not a greyscale ramp. */
 
 :root {
+  /* Native UI (scrollbars, form control popups, autofill) follows the OS unless
+     told otherwise. The tokens below don't, so pin it to the same switch —
+     otherwise a light app in an OS-dark browser gets dark scrollbars and a dark
+     `<select>` popup. */
+  color-scheme: light;
+
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
   --card: oklch(1 0 0);
@@ -51,6 +57,8 @@
 
 .dark,
 [data-theme="dark"] {
+  color-scheme: dark;
+
   --background: oklch(0.145 0 0);
   --foreground: oklch(0.985 0 0);
   --card: oklch(0.205 0 0);
@@ -145,6 +153,17 @@
 }
 
 /* ------------------------------------------------------- custom variants */
+
+/* `dark:` must follow the same switch as the tokens above — the class, not the
+   OS setting. Tailwind v4's stock `dark` variant is `@media (prefers-color-scheme:
+   dark)`, so leaving it alone splits the theme in two: a browser in OS dark mode
+   activates every `dark:` utility while `--background`/`--foreground` stay light,
+   because no `.dark` class is present. The result is light-on-light — `dark:text-
+   slate-100` over a white card is invisible — and it hits Vantage's own kit too
+   (`dark:data-active:bg-input/30` and friends). `:is()` keeps the specificity
+   above the unprefixed utility, so `dark:` still wins when the class is set. */
+@custom-variant dark (&:is(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *));
+
 /* Base UI reports state through `data-open`, `data-checked`, … rather than
    Radix's `data-state="open"`. These variants accept both spellings so the
    component classes read the same either way. */