@squadbase/vantage 0.5.2 → 0.5.3-dev.71d2349

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.2).** APIs may still change between releases.
+> **Status: prototype (v0.5.3).** APIs may still change between releases.
 
 ## Install
 
@@ -111,8 +111,9 @@ skipped with their location reported instead of copied a second time.
 
 ## Documentation
 
-Full guides live in the [Vantage docs](https://github.com/squadbase/vantage-framework/tree/main/docs)
-(bilingual — English under `docs/content/en`, Japanese under `docs/content`).
+Full guides live in the
+[Vantage docs](https://github.com/squadbase/squadbase-monorepo/tree/main/packages/vantage/site)
+(bilingual — English under `site/content/en`, Japanese under `site/content`).
 
 ## License
 

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

package/dist/index.js

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

package/docs/en/agent-skills.md

@@ -15,6 +15,7 @@ All of these target an agent that is **building a Vantage app**.
 | `vantage-app` | Creating an app, and growing a single-file `index.tsx` SPA into a fullstack app with `server/api`, nested layouts, dynamic routes, and 404/error pages |
 | `vantage-add-feature` | Adding a page / API / UI / block (`vantage add` through to `check` / `routes`) |
 | `vantage-pitfalls` | A pitfalls reference (Base UI ≠ Radix, `SelectValue` behavior, never importing `server/` from the client, and more) |
+| `project-storage` | Working with Squadbase Project Storage (uploaded files) from the browser — listing, embedding images / video / PDFs, uploading. For apps running on Squadbase |
 
 ## Placing them
 
@@ -37,6 +38,7 @@ under the root, under `.claude/skills/`, under `.squadbase/skills/`, it doesn't
 ```text
 $ vantage add skill
 Bundled skills:
+  project-storage      .claude/skills/project-storage/
   vantage-add-feature  .claude/skills/vantage-add-feature/
   vantage-app          .claude/skills/vantage-app/
   vantage-pitfalls     not placed
@@ -56,7 +58,8 @@ your-app/
     └── skills/
         ├── vantage-app/SKILL.md
         ├── vantage-add-feature/SKILL.md
-        └── vantage-pitfalls/SKILL.md
+        ├── vantage-pitfalls/SKILL.md
+        └── project-storage/SKILL.md
 ```
 
 Claude Code discovers `.claude/skills/` automatically. The agent loads and follows the matching

package/docs/en/changelog.md

@@ -9,6 +9,23 @@ 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.3
+
+Adds a bundled skill for working with Squadbase Project Storage from the browser.
+Anything on `^0.5.0` picks this up as-is.
+
+### Added
+
+- **A `project-storage` skill now ships with Vantage.** It covers reading and
+  writing Squadbase Project Storage — the files a user uploaded — from a page or
+  component through `useStorage()` from `@squadbase/react`: listing files,
+  embedding images / video / PDFs (including refreshing the short-lived URL),
+  reading file contents, and uploading, deleting or moving.
+
+  Place it like any other skill with `vantage add skill --all` (add `--dir` to
+  choose where it lands). No library code changed, so no app-side change is
+  needed.
+
 ## v0.5.2
 
 Fixes an already-open tab getting stuck on chunks from a build that is no longer

package/docs/ja/agent-skills.md

@@ -15,6 +15,7 @@ Vantage は **Claude Code の Agent Skills** を同梱しています。Skill
 | `vantage-app` | アプリの新規作成と、`index.tsx` 単体の SPA から `server/api`・ネストレイアウト・動的ルート・404/error を備えた fullstack への拡張 |
 | `vantage-add-feature` | ページ / API / UI / ブロックの追加(`vantage add` + `check` / `routes` までの一連) |
 | `vantage-pitfalls` | 落とし穴リファレンス(Base UI ≠ Radix、`SelectValue` の挙動、クライアントから `server/` を import しない など) |
+| `project-storage` | Squadbase の Project Storage(アップロード済みファイル)をブラウザから扱う(一覧、画像 / 動画 / PDF の埋め込み、アップロード)。Squadbase 上で動くアプリ向け |
 
 ## 配置する
 
@@ -37,6 +38,7 @@ vantage add skill --all --force               # 配置済みのコピーをそ
 ```text
 $ vantage add skill
 Bundled skills:
+  project-storage      .claude/skills/project-storage/
   vantage-add-feature  .claude/skills/vantage-add-feature/
   vantage-app          .claude/skills/vantage-app/
   vantage-pitfalls     not placed
@@ -56,7 +58,8 @@ your-app/
     └── skills/
         ├── vantage-app/SKILL.md
         ├── vantage-add-feature/SKILL.md
-        └── vantage-pitfalls/SKILL.md
+        ├── vantage-pitfalls/SKILL.md
+        └── project-storage/SKILL.md
 ```
 
 `.claude/skills/` は Claude Code が自動で認識します。エージェントはタスクに応じて、対応する

package/docs/ja/changelog.md

@@ -8,6 +8,21 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.5.3
+
+Squadbase の Project Storage をブラウザから扱うための Skill を同梱しました。`^0.5.0` を
+指定していればそのまま入ります。
+
+### 追加
+
+- **`project-storage` skill を同梱しました。** Squadbase の Project Storage(ユーザーが
+  アップロードしたファイル)を、`@squadbase/react` の `useStorage()` でページやコンポーネント
+  から扱う手順書です。ファイル一覧、画像 / 動画 / PDF の埋め込み(短命な URL の取り直しを
+  含む)、中身の読み取り、アップロードと削除・移動を扱います。
+
+  配置は他の skill と同じで `vantage add skill --all`(置き場を選ぶなら `--dir`)。
+  ライブラリのコードは変わっていないので、アプリ側の変更は要りません。
+
 ## v0.5.2
 
 再公開でビルドが差し替わったとき、開いたままのタブが古い chunk を取りに行って動かなくなる

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.5.2",
+  "version": "0.5.3-dev.71d2349",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",
   "author": "Squadbase",
-  "homepage": "https://github.com/squadbase/vantage-framework/tree/main/packages/vantage#readme",
+  "homepage": "https://github.com/squadbase/squadbase-monorepo/tree/main/packages/vantage#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/squadbase/vantage-framework.git",
+    "url": "git+https://github.com/squadbase/squadbase-monorepo.git",
     "directory": "packages/vantage"
   },
   "bugs": {
-    "url": "https://github.com/squadbase/vantage-framework/issues"
+    "url": "https://github.com/squadbase/squadbase-monorepo/issues"
   },
   "keywords": [
     "vantage",
@@ -25,10 +25,11 @@
     "tanstack"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "bin": {
     "vantage": "./dist/cli.js"
@@ -93,7 +94,12 @@
     "dev": "tsup --watch --no-dts",
     "dev:types": "tsc --noEmit --watch",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "node scripts/build-docs.mjs && node scripts/build.mjs"
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "node scripts/build-docs.mjs && node scripts/build.mjs",
+    "release": "npm publish --@squadbase:registry=https://registry.npmjs.org",
+    "site:install": "npm --prefix site install",
+    "site:dev": "npm --prefix site run dev",
+    "site:build": "npm --prefix site run build"
   },
   "dependencies": {
     "@base-ui/react": "^1.6.0",

package/skills/project-storage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: project-storage
+description: Squadbase の Project Storage(アップロード済みファイル)を @squadbase/react の useStorage() でブラウザから扱う手順。ファイル一覧、画像 / 動画 / PDF の埋め込み、中身の読み取り、アップロードと削除・移動。ページやコンポーネントがアップロード済みファイルを表示・埋め込み・アップロードするときに参照する。
+---
+
+# Project Storage(ブラウザ側)
+
+Squadbase の **Project Storage** を React コンポーネントから読み書きする手順。Squadbase 上で
+動くアプリでは資格情報も設定も要らず、そのまま動く。サーバー(`server/api/**`)からストレージを
+触る API は別物で、ここでは扱わない。
+
+## import は `@squadbase/react` から直接
+
+「import は `@squadbase/vantage` のサブパス経由」はフレームワークが所有するものの話。
+**`@squadbase/react` は Squadbase プラットフォームの SDK なので直接 import する**
+(`SquadbaseProvider` / `useUser` と同じ)。
+
+```tsx
+import { useStorage } from "@squadbase/react"
+
+const storage = useStorage()
+// 呼び出しはすべて storage.uploads.* の下
+```
+
+`useStorage()` が返すクライアントは安定なので、コンポーネント先頭で呼んで `useQuery` /
+`useMutation` の中で使ってよい。データ取得のフックは `@squadbase/vantage/query` から取る
+(`@tanstack/*` は直接 import しない)。
+
+## API
+
+すべて async。`key` はストレージ内の**相対**パス(例: `reports/2025-q1.pdf`)で、先頭に
+スラッシュを付けない。
+
+読み取り:
+
+- `list(prefix?, options?)` → `{ objects, commonPrefixes, nextCursor? }`。`objects` は
+  `{ key, size, lastModified }[]`。`options.delimiter = "/"` でフォルダ表示(サブフォルダが
+  `commonPrefixes` に入る)、省略すると再帰的なフラット一覧。`options.limit` / `options.cursor`
+  でページング(`cursor` は前回の `nextCursor`)
+- `head(key)` → `{ key, size, contentType, createdAt }`。メタ情報だけで本体は取らない
+- `getUrl(key)` → `{ url, expiresAt }`。埋め込み用の一時 URL
+- `get(key)` → 生の `Response`。`.json()` / `.text()` / `.blob()` / `.arrayBuffer()` で読む
+
+書き込み:
+
+- `put(key, data, options?)` → `void`。`data` は `Blob`(`File` を含む) / `ArrayBuffer` /
+  `Uint8Array` / `string`
+- `delete(key)` → `void`
+- `copy(srcKey, destKey, options?)` / `move(srcKey, destKey, options?)` → `void`
+
+## 一覧を出す
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const { data, isPending, isError } = useQuery({
+  queryKey: ["storage", "list", prefix],
+  queryFn: () => storage.uploads.list(prefix, { delimiter: "/" }),
+})
+```
+
+`data.commonPrefixes` をフォルダ、`data.objects` をファイルとして描く。プレフィックス配下を
+まとめて出すなら `delimiter` を省く。
+
+## 画像 / 動画 / PDF を埋め込む
+
+埋め込みには URL が要るので `getUrl` を使う。**URL には期限がある**ので、切れる前に取り直す:
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+function useStorageUrl(key: string) {
+  const storage = useStorage()
+  return useQuery({
+    queryKey: ["storage", "url", key],
+    queryFn: () => storage.uploads.getUrl(key),
+    refetchInterval: (query) => {
+      const expiresAt = query.state.data?.expiresAt
+      if (!expiresAt) return false
+      // 期限の 60 秒前に取り直す
+      return Math.max(0, new Date(expiresAt).getTime() - Date.now() - 60_000)
+    },
+  })
+}
+```
+
+```tsx
+import { ErrorState, Loading } from "@squadbase/vantage/ui"
+
+const { data, isPending, isError } = useStorageUrl("reports/cover.png")
+if (isPending) return <Loading />
+if (isError) return <ErrorState message="ファイルを読み込めませんでした" />
+return <img src={data.url} alt="" className="w-full rounded-lg" />
+```
+
+動画は `<video src={data.url} controls className="w-full rounded-lg" />`、PDF は
+`<iframe src={data.url} className="h-[80vh] w-full rounded-lg border border-border" />`。
+
+## 中身を JS で読む
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["storage", "content", key],
+  queryFn: async () => {
+    const res = await storage.uploads.get(key)
+    return (await res.json()) as Row[] // または res.text()
+  },
+})
+```
+
+## アップロードする
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useMutation, useQueryClient } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const queryClient = useQueryClient()
+const upload = useMutation({
+  mutationFn: (file: File) =>
+    storage.uploads.put(`uploads/${file.name}`, file, { contentType: file.type }),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["storage", "list"] }),
+})
+
+<input
+  type="file"
+  onChange={(e) => {
+    const file = e.target.files?.[0]
+    if (file) upload.mutate(file)
+  }}
+/>
+```
+
+`File` はそのまま `put` に渡す。書き込み後は該当する `["storage", "list", …]` を invalidate して
+UI を追従させる。
+
+## 落とし穴
+
+- **`getUrl` の URL は短命。** 結果を永続化したり長寿命のキャッシュに入れたりしない。
+  `expiresAt` の前に取り直す(上のフック)。`<img src>` に一度入れて放置すると、開いたままの
+  画面で後から読み込まれた分が失敗する
+- **`put` の `contentType` の既定は `application/octet-stream`。** 後で埋め込むもの(画像・動画・
+  PDF)には `file.type` を必ず渡す。付けないとブラウザが表示せずダウンロードに落ちる
+- **`key` は相対パス。** 先頭にスラッシュを付けない。`getUrl` を通さず `<img src="/foo.png">` の
+  ような静的パスで参照しない ― ストレージはアプリの `public/` ではない
+- **`copy` / `move` は既定で既存の宛先を上書きする。** 残したいときは `{ overwrite: false }`
+- **サーバー(`server/api/**`)からは呼ばない。** `useStorage` はブラウザ側の API
+
+---
+
+## 関連スキル
+
+- `vantage-add-feature` — ページ / API / コンポーネントを 1 つ足す手順
+- `vantage-pitfalls` — UI・配色・ルーティングの落とし穴

package/templates/AGENTS.md

@@ -379,6 +379,7 @@ body・レスポンスの status と形)まで出る。`vantage check --json` /
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
+- **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
 手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
 `.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**