@wcstack/typescript 1.32.0 → 2.0.0

package/README.ja.md

@@ -1,106 +1,106 @@
-# @wcstack/typescript
-
-> 🤖 **AI coding agents**: This README is a package-level reference, not the primary entry point for building a wcstack application. If you have not already done so, first read the repository [README](https://github.com/wcstack/wcstack#readme) and [AGENTS.md](https://github.com/wcstack/wcstack/blob/main/AGENTS.md), then use the [wcstack-app skill](https://github.com/wcstack/wcstack-skill).
-
-**もし、state に書いた型がそれをバインドする HTML まで届いたら？**
-
-`@wcstack/state` のページは DOM と state をパス文字列（`users.*.name`）で結びます。TypeScript の state ファイルはそのパス全部と型を知っています — しかし HTML は `.d.ts` を消費できず、静的検証器（`wcs-validate`・VS Code 拡張）はインラインスクリプトを型注釈を理解しない正規表現アナライザで読みます。`users: [] as { name: string }[]` では `users.*.name` が解決できず、本物の typo は warning 止まり、正しいバインドには偽警告が付きます。
-
-`@wcstack/typescript` はこの穴をコマンド 1 つで塞ぎます。`wcs-schema` は state ファイルを TypeScript コンパイラ API でコンパイルし、検証器が消費する sidecar `wcstack.manifest.json` の `stateSchema` を書き出します — CI でも、どのエディタでも。manifest は**派生物**です: 正本は型のままで、乖離すれば `wcs-schema check` が CI を落とします。
-
-```bash
-npm install -D @wcstack/typescript typescript
-npx wcs-schema emit src/state.ts          # ./wcstack.manifest.json を書く
-npx wcs-validate --strict index.html      # typo は error に、偽警告は消える
-```
-
-ランタイム依存ゼロ。`typescript` は peer dependency — プロジェクト自身のコンパイラを使います。
-
-## コマンド
-
-### `wcs-schema emit <state.ts|state.js> [options]`
-
-ファイルの `export default` から `states[<name>].stateSchema` を生成します（`defineState(...)` は構文的に剥がすので、このパッケージは `@wcstack/state` を解決できなくても動きます）。生成結果は書き出す前に検証器自身の manifest 検査を通します。
-
-| オプション | 説明 |
-|---|---|
-| `--state=<name>` | state 名（既定 `default`） |
-| `--out=<path>` | 出力先 manifest（作業ディレクトリ相対・既定 `wcstack.manifest.json`）。`--out=-` で stdout |
-| `--merge` | 既存 manifest の他の内容（他 state・`filters`・`listContexts`）を保持し、この state の `stateSchema` だけ置き換える。同じ state の手書き schema は合成されず置き換わる |
-| `--tsconfig=<path>` | コンパイルに使う `tsconfig.json`（既定: state ファイルから上に辿って最も近いもの、無ければ組み込み既定） |
-| `--max-depth=<n>` | ここより深い入れ子は素の `{}` で打ち切る（既定 `5` = 検証器の探索予算と同じ） |
-
-exit code: `0` 書き出し済み · `2` usage エラー / 読めない / 構文エラー / 生成物が自己検査に落ちた。
-
-### `wcs-schema check <state.ts|state.js> [options]`
-
-schema を再生成し、`--manifest=<path>`（既定 `wcstack.manifest.json`）の内容とキー順を無視して比較します。
-
-exit code: `0` 最新 · `1` 乖離あり（変更は JSON pointer で列挙: `+` 型にだけある / `-` manifest にだけある / `~` 違う） · `2` usage エラー / manifest が無い / その state の `stateSchema` がまだ無い。
-
-推奨する CI ゲート:
-
-```bash
-npx wcs-schema check src/state.ts && npx wcs-validate --strict index.html
-```
-
-### `wcs-tsc [--url-imports=any|error] [--wcs-defaults] [tsc の引数...]`
-
-`.html` に対する `tsc`: 各 `<wcs-state>` のインライン `<script type="module">` を VS Code 拡張と同じ言語プラグイン（型付き `this`・自動 `defineState` ラップ・bare でも CDN URL でも `@wcstack/state` import を除去）で型検査し、診断は HTML の位置を指します:
-
-```bash
-npm i -D @volar/typescript@~2.4.0 @volar/language-core@~2.4.0   # optional peer・wcs-tsc だけが必要
-npx wcs-tsc --noEmit
-# index.html(9,14): error TS2551: Property 'coutn' does not exist on type '_WcsThis<…>'. Did you mean 'count'?
-```
-
-| オプション | 説明 |
-|---|---|
-| `--url-imports=any`（既定） | 全ての `http(s)://` モジュール import を `any` に型付ける — buildless なページは tsc が解決できない CDN から import する |
-| `--url-imports=error` | URL import をそのまま残す（それぞれ TS2307） |
-| `--wcs-defaults` | プロジェクトの tsconfig に `**/*.html` を覆う `include`・`noImplicitThis`・`allowJs`・`checkJs` が無ければ、元を extends してそれらを足した一時 config で実行する（無指定なら警告だけで HTML が検査されないことがある） |
-| それ以外 | tsc にそのまま渡す（`-p`・`--noEmit` …） |
-
-exit code は tsc のもの（`0` クリーン・診断があれば非ゼロ）。`typescript` / `@volar/typescript` が解決できないときと不正なオプションは `2`。1 ページに複数の `<wcs-state>` があれば 1 本の仮想モジュールに合成（import は巻き上げ・各ブロックは自分のスコープ）し、インライン state の無いページは空のモジュールになります。仕組みは vue-tsc と同じ: `@volar/typescript` の `runTsc` がプロジェクト自身の `typescript/lib/tsc.js` にパッチを当てます。
-
-## 生成される schema の中身
-
-sidecar 規範が許す JSON-Schema サブセットだけ（`type` / `properties` / `required` / `items` / `enum` / `const` / `anyOf`）:
-
-| TypeScript | stateSchema |
-|---|---|
-| `string` / `number` / `boolean` / `null` | `{ "type": … }`（`integer` は使わず全て `number`） |
-| `"a" \| "b"`、`1 \| 2` | `{ "type": "string", "enum": ["a", "b"] }` |
-| `T[]`、`readonly T[]`、タプル | `{ "type": "array", "items": … }` |
-| `T \| null` | `{ "anyOf": [T, { "type": "null" }] }` |
-| `T \| undefined`、`x?: T` | `T`。`x` は `required` に入らない |
-| `A \| B`（オブジェクトや混在プリミティブ） | `{ "anyOf": [A, B] }` |
-| 自分のコードのオブジェクトリテラル / interface / class | `{ "type": "object", "properties": …, "required": … }` |
-| `Date`、`Map`、`Set`、DOM 型、ライブラリ由来の型、`any`、`unknown`、`Record<string, T>` | **素の `{}`** |
-| `get x(): T` | `x: T` — getter はメンバー |
-| `get "users.*.ageCategory"(): string` | `users.items.properties.ageCategory` に注入 — パス getter は計算先のパスのメンバー |
-| メソッド、関数値プロパティ、`$` 始まりキー（`$watch`・`$commandTokens` …） | 捨てる |
-| `--max-depth` より深い入れ子 | 素の `{}` |
-
-素の `{}` が要点です: 検証器はこれを *unknown* として扱いその下では沈黙しますが、メンバーを欠く型付きオブジェクトは *nonexistent* で **error** です。`Date` や `Record<string, unknown>` の下のパスが偽 error になることはありません。
-
-## ライブラリ API
-
-```ts
-import { generateStateSchema, buildManifest, compareStateSchema } from "@wcstack/typescript";
-
-const { schema, warnings } = generateStateSchema("src/state.ts");   // { tsconfig?, maxDepth? }
-const manifest = buildManifest("default", schema /*, 既存の manifest オブジェクト */);
-const result = compareStateSchema(JSON.stringify(manifest), "default", schema); // { kind: "same" } | { kind: "differs", changes } | …
-```
-
-`loadStateFile` / `stateTypeToSchema` は 2 つの半分（コンパイラ program・型 → schema）を別々に組み合わせたいツール向けに公開しています。
-
-## 位置づけ
-
-- 検証器側 — 最近傍 `wcstack.manifest.json` の発見、`wcs/path-nonexistent`、`wcs/path-type-mismatch` — は [`@wcstack/lint`](../lint/README.ja.md#state-の契約を宣言するstateschema) と、規範としては [`docs/wcstack-manifest-schema.md`](https://github.com/wcstack/wcstack/blob/main/docs/wcstack-manifest-schema.md) にあります。
-- wcstack アプリの TypeScript の話全体（`defineState` による `this` の型付け、このパッケージ、tag name map、`wcs-tsc`）は [`docs/typescript.ja.md`](https://github.com/wcstack/wcstack/blob/main/docs/typescript.ja.md) にまとめています。
-
-## License
-
-MIT
+# @wcstack/typescript
+
+> 🤖 **AI coding agents**: This README is a package-level reference, not the primary entry point for building a wcstack application. If you have not already done so, first read the repository [README](https://github.com/wcstack/wcstack#readme) and [AGENTS.md](https://github.com/wcstack/wcstack/blob/main/AGENTS.md), then use the [wcstack-app skill](https://github.com/wcstack/wcstack-skill).
+
+**もし、state に書いた型がそれをバインドする HTML まで届いたら？**
+
+`@wcstack/state` のページは DOM と state をパス文字列（`users.*.name`）で結びます。TypeScript の state ファイルはそのパス全部と型を知っています — しかし HTML は `.d.ts` を消費できず、静的検証器（`wcs-validate`・VS Code 拡張）はインラインスクリプトを型注釈を理解しない正規表現アナライザで読みます。`users: [] as { name: string }[]` では `users.*.name` が解決できず、本物の typo は warning 止まり、正しいバインドには偽警告が付きます。
+
+`@wcstack/typescript` はこの穴をコマンド 1 つで塞ぎます。`wcs-schema` は state ファイルを TypeScript コンパイラ API でコンパイルし、検証器が消費する sidecar `wcstack.manifest.json` の `stateSchema` を書き出します — CI でも、どのエディタでも。manifest は**派生物**です: 正本は型のままで、乖離すれば `wcs-schema check` が CI を落とします。
+
+```bash
+npm install -D @wcstack/typescript typescript
+npx wcs-schema emit src/state.ts          # ./wcstack.manifest.json を書く
+npx wcs-validate --strict index.html      # typo は error に、偽警告は消える
+```
+
+ランタイム依存ゼロ。`typescript` は peer dependency — プロジェクト自身のコンパイラを使います。
+
+## コマンド
+
+### `wcs-schema emit <state.ts|state.js> [options]`
+
+ファイルの `export default` から `states[<name>].stateSchema` を生成します（`defineState(...)` は構文的に剥がすので、このパッケージは `@wcstack/state` を解決できなくても動きます）。生成結果は書き出す前に検証器自身の manifest 検査を通します。
+
+| オプション | 説明 |
+|---|---|
+| `--state=<name>` | state 名（既定 `default`） |
+| `--out=<path>` | 出力先 manifest（作業ディレクトリ相対・既定 `wcstack.manifest.json`）。`--out=-` で stdout |
+| `--merge` | 既存 manifest の他の内容（他 state・`filters`・`listContexts`）を保持し、この state の `stateSchema` だけ置き換える。同じ state の手書き schema は合成されず置き換わる |
+| `--tsconfig=<path>` | コンパイルに使う `tsconfig.json`（既定: state ファイルから上に辿って最も近いもの、無ければ組み込み既定） |
+| `--max-depth=<n>` | ここより深い入れ子は素の `{}` で打ち切る（既定 `5` = 検証器の探索予算と同じ） |
+
+exit code: `0` 書き出し済み · `2` usage エラー / 読めない / 構文エラー / 生成物が自己検査に落ちた。
+
+### `wcs-schema check <state.ts|state.js> [options]`
+
+schema を再生成し、`--manifest=<path>`（既定 `wcstack.manifest.json`）の内容とキー順を無視して比較します。
+
+exit code: `0` 最新 · `1` 乖離あり（変更は JSON pointer で列挙: `+` 型にだけある / `-` manifest にだけある / `~` 違う） · `2` usage エラー / manifest が無い / その state の `stateSchema` がまだ無い。
+
+推奨する CI ゲート:
+
+```bash
+npx wcs-schema check src/state.ts && npx wcs-validate --strict index.html
+```
+
+### `wcs-tsc [--url-imports=any|error] [--wcs-defaults] [tsc の引数...]`
+
+`.html` に対する `tsc`: 各 `<wcs-state>` のインライン `<script type="module">` を VS Code 拡張と同じ言語プラグイン（型付き `this`・自動 `defineState` ラップ・bare でも CDN URL でも `@wcstack/state` import を除去）で型検査し、診断は HTML の位置を指します:
+
+```bash
+npm i -D @volar/typescript@~2.4.0 @volar/language-core@~2.4.0   # optional peer・wcs-tsc だけが必要
+npx wcs-tsc --noEmit
+# index.html(9,14): error TS2551: Property 'coutn' does not exist on type '_WcsThis<…>'. Did you mean 'count'?
+```
+
+| オプション | 説明 |
+|---|---|
+| `--url-imports=any`（既定） | 全ての `http(s)://` モジュール import を `any` に型付ける — buildless なページは tsc が解決できない CDN から import する |
+| `--url-imports=error` | URL import をそのまま残す（それぞれ TS2307） |
+| `--wcs-defaults` | プロジェクトの tsconfig に `**/*.html` を覆う `include`・`noImplicitThis`・`allowJs`・`checkJs` が無ければ、元を extends してそれらを足した一時 config で実行する（無指定なら警告だけで HTML が検査されないことがある） |
+| それ以外 | tsc にそのまま渡す（`-p`・`--noEmit` …） |
+
+exit code は tsc のもの（`0` クリーン・診断があれば非ゼロ）。`typescript` / `@volar/typescript` が解決できないときと不正なオプションは `2`。1 ページに複数の `<wcs-state>` があれば 1 本の仮想モジュールに合成（import は巻き上げ・各ブロックは自分のスコープ）し、インライン state の無いページは空のモジュールになります。仕組みは vue-tsc と同じ: `@volar/typescript` の `runTsc` がプロジェクト自身の `typescript/lib/tsc.js` にパッチを当てます。
+
+## 生成される schema の中身
+
+sidecar 規範が許す JSON-Schema サブセットだけ（`type` / `properties` / `required` / `items` / `enum` / `const` / `anyOf`）:
+
+| TypeScript | stateSchema |
+|---|---|
+| `string` / `number` / `boolean` / `null` | `{ "type": … }`（`integer` は使わず全て `number`） |
+| `"a" \| "b"`、`1 \| 2` | `{ "type": "string", "enum": ["a", "b"] }` |
+| `T[]`、`readonly T[]`、タプル | `{ "type": "array", "items": … }` |
+| `T \| null` | `{ "anyOf": [T, { "type": "null" }] }` |
+| `T \| undefined`、`x?: T` | `T`。`x` は `required` に入らない |
+| `A \| B`（オブジェクトや混在プリミティブ） | `{ "anyOf": [A, B] }` |
+| 自分のコードのオブジェクトリテラル / interface / class | `{ "type": "object", "properties": …, "required": … }` |
+| `Date`、`Map`、`Set`、DOM 型、ライブラリ由来の型、`any`、`unknown`、`Record<string, T>` | **素の `{}`** |
+| `get x(): T` | `x: T` — getter はメンバー |
+| `get "users.*.ageCategory"(): string` | `users.items.properties.ageCategory` に注入 — パス getter は計算先のパスのメンバー |
+| メソッド、関数値プロパティ、`$` 始まりキー（`$watch`・`$commandTokens` …） | 捨てる |
+| `--max-depth` より深い入れ子 | 素の `{}` |
+
+素の `{}` が要点です: 検証器はこれを *unknown* として扱いその下では沈黙しますが、メンバーを欠く型付きオブジェクトは *nonexistent* で **error** です。`Date` や `Record<string, unknown>` の下のパスが偽 error になることはありません。
+
+## ライブラリ API
+
+```ts
+import { generateStateSchema, buildManifest, compareStateSchema } from "@wcstack/typescript";
+
+const { schema, warnings } = generateStateSchema("src/state.ts");   // { tsconfig?, maxDepth? }
+const manifest = buildManifest("default", schema /*, 既存の manifest オブジェクト */);
+const result = compareStateSchema(JSON.stringify(manifest), "default", schema); // { kind: "same" } | { kind: "differs", changes } | …
+```
+
+`loadStateFile` / `stateTypeToSchema` は 2 つの半分（コンパイラ program・型 → schema）を別々に組み合わせたいツール向けに公開しています。
+
+## 位置づけ
+
+- 検証器側 — 最近傍 `wcstack.manifest.json` の発見、`wcs/path-nonexistent`、`wcs/path-type-mismatch` — は [`@wcstack/lint`](../lint/README.ja.md#state-の契約を宣言するstateschema) と、規範としては [`docs/wcstack-manifest-schema.md`](https://github.com/wcstack/wcstack/blob/main/docs/wcstack-manifest-schema.md) にあります。
+- wcstack アプリの TypeScript の話全体（`defineState` による `this` の型付け、このパッケージ、tag name map、`wcs-tsc`）は [`docs/typescript.ja.md`](https://github.com/wcstack/wcstack/blob/main/docs/typescript.ja.md) にまとめています。
+
+## License
+
+MIT

package/README.md

@@ -1,106 +1,106 @@
-# @wcstack/typescript
-
-> 🤖 **AI coding agents**: This README is a package-level reference, not the primary entry point for building a wcstack application. If you have not already done so, first read the repository [README](https://github.com/wcstack/wcstack#readme) and [AGENTS.md](https://github.com/wcstack/wcstack/blob/main/AGENTS.md), then use the [wcstack-app skill](https://github.com/wcstack/wcstack-skill).
-
-**What if the types you already wrote for your state reached the HTML that binds to it?**
-
-`@wcstack/state` pages bind DOM to state through path strings (`users.*.name`). A TypeScript state file already knows every one of those paths and its type — but HTML cannot consume a `.d.ts`, and the static validator (`wcs-validate`, the VS Code extension) reads the inline script with a regular-expression analyzer that does not understand annotations: `users: [] as { name: string }[]` leaves `users.*.name` unresolvable, so a real typo is only a warning and a correct binding gets a false one.
-
-`@wcstack/typescript` closes that gap with one command. `wcs-schema` compiles the state file with the TypeScript compiler API and writes the sidecar `wcstack.manifest.json` `stateSchema` that the validator consumes — in CI and in every editor. The manifest is a **derived artifact**: the type stays the source of truth, and `wcs-schema check` fails CI when they drift.
-
-```bash
-npm install -D @wcstack/typescript typescript
-npx wcs-schema emit src/state.ts          # writes ./wcstack.manifest.json
-npx wcs-validate --strict index.html      # typos are now errors, false warnings are gone
-```
-
-Zero runtime dependencies. `typescript` is a peer dependency — the project's own compiler is used.
-
-## Commands
-
-### `wcs-schema emit <state.ts|state.js> [options]`
-
-Generates `states[<name>].stateSchema` from the file's `export default` (a `defineState(...)` call is unwrapped syntactically, so the package does not even need to resolve `@wcstack/state`). The result is run through the validator core's own manifest check before anything is written.
-
-| Option | Description |
-|---|---|
-| `--state=<name>` | State name (default `default`) |
-| `--out=<path>` | Output manifest, relative to the working directory (default `wcstack.manifest.json`). `--out=-` prints to stdout |
-| `--merge` | Keep everything else in an existing manifest (other states, `filters`, `listContexts`) and replace only this state's `stateSchema`. A hand-written schema for the same state is replaced, not merged |
-| `--tsconfig=<path>` | `tsconfig.json` to compile with (default: the nearest one above the state file, else built-in defaults) |
-| `--max-depth=<n>` | Object nesting depth at which the schema stops with a bare `{}` (default `5`, the validator's own budget) |
-
-Exit codes: `0` written · `2` usage error, unreadable file, syntax error, or a generated manifest that failed its self-check.
-
-### `wcs-schema check <state.ts|state.js> [options]`
-
-Regenerates the schema and compares it with `--manifest=<path>` (default `wcstack.manifest.json`), key order ignored.
-
-Exit codes: `0` up to date · `1` drift (each change is listed as a JSON pointer: `+` only in the type, `-` only in the manifest, `~` different) · `2` usage error, missing manifest, or the state has no `stateSchema` yet.
-
-The recommended CI gate is
-
-```bash
-npx wcs-schema check src/state.ts && npx wcs-validate --strict index.html
-```
-
-### `wcs-tsc [--url-imports=any|error] [--wcs-defaults] [tsc arguments...]`
-
-`tsc` over `.html`: every `<wcs-state>` inline `<script type="module">` is type-checked through the same language plugin the VS Code extension uses (typed `this`, automatic `defineState` wrap, `@wcstack/state` imports stripped whether bare or a CDN URL), and diagnostics point into the HTML:
-
-```bash
-npm i -D @volar/typescript@~2.4.0 @volar/language-core@~2.4.0   # optional peers, only wcs-tsc needs them
-npx wcs-tsc --noEmit
-# index.html(9,14): error TS2551: Property 'coutn' does not exist on type '_WcsThis<…>'. Did you mean 'count'?
-```
-
-| Option | Description |
-|---|---|
-| `--url-imports=any` (default) | Every `http(s)://` module import types as `any` — buildless pages import from a CDN that tsc cannot resolve |
-| `--url-imports=error` | Leave URL imports alone (TS2307 each) |
-| `--wcs-defaults` | If the project tsconfig lacks `include` covering `**/*.html`, `noImplicitThis`, `allowJs` or `checkJs`, run with a temporary config that extends it and adds them (otherwise only a warning is printed and HTML may go unchecked) |
-| anything else | passed to tsc verbatim (`-p`, `--noEmit`, …) |
-
-Exit codes are tsc's (`0` clean, non-zero with diagnostics); `2` when `typescript` / `@volar/typescript` cannot be resolved or an option is invalid. A page with several `<wcs-state>` blocks is combined into one virtual module (imports hoisted, each block in its own scope); a page without inline state is an empty module. The mechanism is vue-tsc's: `@volar/typescript`'s `runTsc` patches the project's own `typescript/lib/tsc.js`.
-
-## What the generated schema contains
-
-Only the JSON-Schema subset the sidecar spec allows (`type`, `properties`, `required`, `items`, `enum`, `const`, `anyOf`):
-
-| TypeScript | stateSchema |
-|---|---|
-| `string` / `number` / `boolean` / `null` | `{ "type": … }` (`integer`-less: numbers are `number`) |
-| `"a" \| "b"`, `1 \| 2` | `{ "type": "string", "enum": ["a", "b"] }` |
-| `T[]`, `readonly T[]`, tuples | `{ "type": "array", "items": … }` |
-| `T \| null` | `{ "anyOf": [T, { "type": "null" }] }` |
-| `T \| undefined`, `x?: T` | `T`, and `x` is left out of `required` |
-| `A \| B` (objects or mixed primitives) | `{ "anyOf": [A, B] }` |
-| object literals, interfaces, classes from your code | `{ "type": "object", "properties": …, "required": … }` |
-| `Date`, `Map`, `Set`, DOM types, anything from a library, `any`, `unknown`, `Record<string, T>` | a **bare `{}`** |
-| `get x(): T` | `x: T` — getters are members |
-| `get "users.*.ageCategory"(): string` | injected as `users.items.properties.ageCategory` — a path getter is a member at the path it computes |
-| methods, function-valued properties, `$`-prefixed keys (`$watch`, `$commandTokens`, …) | dropped |
-| nesting deeper than `--max-depth` | a bare `{}` |
-
-The bare `{}` matters: the validator treats it as *unknown* and stays silent below it, whereas a typed object that lacks a member is *nonexistent* and an **error**. A `Date` or a `Record<string, unknown>` therefore never produces false errors for the paths under it.
-
-## Library API
-
-```ts
-import { generateStateSchema, buildManifest, compareStateSchema } from "@wcstack/typescript";
-
-const { schema, warnings } = generateStateSchema("src/state.ts");   // { tsconfig?, maxDepth? }
-const manifest = buildManifest("default", schema /*, existingManifestObject */);
-const result = compareStateSchema(JSON.stringify(manifest), "default", schema); // { kind: "same" } | { kind: "differs", changes } | …
-```
-
-`loadStateFile` / `stateTypeToSchema` expose the two halves (compiler program, type → schema) for tools that want to compose them differently.
-
-## Where this fits
-
-- The validator side — discovery of the nearest `wcstack.manifest.json`, `wcs/path-nonexistent`, `wcs/path-type-mismatch` — is documented in [`@wcstack/lint`](../lint/README.md#declaring-a-state-contract-stateschema) and normatively in [`docs/wcstack-manifest-schema.md`](https://github.com/wcstack/wcstack/blob/main/docs/wcstack-manifest-schema.md).
-- The full TypeScript story for wcstack apps (typing `this` with `defineState`, this package, tag name maps, `wcs-tsc`) is collected in [`docs/typescript.md`](https://github.com/wcstack/wcstack/blob/main/docs/typescript.md).
-
-## License
-
-MIT
+# @wcstack/typescript
+
+> 🤖 **AI coding agents**: This README is a package-level reference, not the primary entry point for building a wcstack application. If you have not already done so, first read the repository [README](https://github.com/wcstack/wcstack#readme) and [AGENTS.md](https://github.com/wcstack/wcstack/blob/main/AGENTS.md), then use the [wcstack-app skill](https://github.com/wcstack/wcstack-skill).
+
+**What if the types you already wrote for your state reached the HTML that binds to it?**
+
+`@wcstack/state` pages bind DOM to state through path strings (`users.*.name`). A TypeScript state file already knows every one of those paths and its type — but HTML cannot consume a `.d.ts`, and the static validator (`wcs-validate`, the VS Code extension) reads the inline script with a regular-expression analyzer that does not understand annotations: `users: [] as { name: string }[]` leaves `users.*.name` unresolvable, so a real typo is only a warning and a correct binding gets a false one.
+
+`@wcstack/typescript` closes that gap with one command. `wcs-schema` compiles the state file with the TypeScript compiler API and writes the sidecar `wcstack.manifest.json` `stateSchema` that the validator consumes — in CI and in every editor. The manifest is a **derived artifact**: the type stays the source of truth, and `wcs-schema check` fails CI when they drift.
+
+```bash
+npm install -D @wcstack/typescript typescript
+npx wcs-schema emit src/state.ts          # writes ./wcstack.manifest.json
+npx wcs-validate --strict index.html      # typos are now errors, false warnings are gone
+```
+
+Zero runtime dependencies. `typescript` is a peer dependency — the project's own compiler is used.
+
+## Commands
+
+### `wcs-schema emit <state.ts|state.js> [options]`
+
+Generates `states[<name>].stateSchema` from the file's `export default` (a `defineState(...)` call is unwrapped syntactically, so the package does not even need to resolve `@wcstack/state`). The result is run through the validator core's own manifest check before anything is written.
+
+| Option | Description |
+|---|---|
+| `--state=<name>` | State name (default `default`) |
+| `--out=<path>` | Output manifest, relative to the working directory (default `wcstack.manifest.json`). `--out=-` prints to stdout |
+| `--merge` | Keep everything else in an existing manifest (other states, `filters`, `listContexts`) and replace only this state's `stateSchema`. A hand-written schema for the same state is replaced, not merged |
+| `--tsconfig=<path>` | `tsconfig.json` to compile with (default: the nearest one above the state file, else built-in defaults) |
+| `--max-depth=<n>` | Object nesting depth at which the schema stops with a bare `{}` (default `5`, the validator's own budget) |
+
+Exit codes: `0` written · `2` usage error, unreadable file, syntax error, or a generated manifest that failed its self-check.
+
+### `wcs-schema check <state.ts|state.js> [options]`
+
+Regenerates the schema and compares it with `--manifest=<path>` (default `wcstack.manifest.json`), key order ignored.
+
+Exit codes: `0` up to date · `1` drift (each change is listed as a JSON pointer: `+` only in the type, `-` only in the manifest, `~` different) · `2` usage error, missing manifest, or the state has no `stateSchema` yet.
+
+The recommended CI gate is
+
+```bash
+npx wcs-schema check src/state.ts && npx wcs-validate --strict index.html
+```
+
+### `wcs-tsc [--url-imports=any|error] [--wcs-defaults] [tsc arguments...]`
+
+`tsc` over `.html`: every `<wcs-state>` inline `<script type="module">` is type-checked through the same language plugin the VS Code extension uses (typed `this`, automatic `defineState` wrap, `@wcstack/state` imports stripped whether bare or a CDN URL), and diagnostics point into the HTML:
+
+```bash
+npm i -D @volar/typescript@~2.4.0 @volar/language-core@~2.4.0   # optional peers, only wcs-tsc needs them
+npx wcs-tsc --noEmit
+# index.html(9,14): error TS2551: Property 'coutn' does not exist on type '_WcsThis<…>'. Did you mean 'count'?
+```
+
+| Option | Description |
+|---|---|
+| `--url-imports=any` (default) | Every `http(s)://` module import types as `any` — buildless pages import from a CDN that tsc cannot resolve |
+| `--url-imports=error` | Leave URL imports alone (TS2307 each) |
+| `--wcs-defaults` | If the project tsconfig lacks `include` covering `**/*.html`, `noImplicitThis`, `allowJs` or `checkJs`, run with a temporary config that extends it and adds them (otherwise only a warning is printed and HTML may go unchecked) |
+| anything else | passed to tsc verbatim (`-p`, `--noEmit`, …) |
+
+Exit codes are tsc's (`0` clean, non-zero with diagnostics); `2` when `typescript` / `@volar/typescript` cannot be resolved or an option is invalid. A page with several `<wcs-state>` blocks is combined into one virtual module (imports hoisted, each block in its own scope); a page without inline state is an empty module. The mechanism is vue-tsc's: `@volar/typescript`'s `runTsc` patches the project's own `typescript/lib/tsc.js`.
+
+## What the generated schema contains
+
+Only the JSON-Schema subset the sidecar spec allows (`type`, `properties`, `required`, `items`, `enum`, `const`, `anyOf`):
+
+| TypeScript | stateSchema |
+|---|---|
+| `string` / `number` / `boolean` / `null` | `{ "type": … }` (`integer`-less: numbers are `number`) |
+| `"a" \| "b"`, `1 \| 2` | `{ "type": "string", "enum": ["a", "b"] }` |
+| `T[]`, `readonly T[]`, tuples | `{ "type": "array", "items": … }` |
+| `T \| null` | `{ "anyOf": [T, { "type": "null" }] }` |
+| `T \| undefined`, `x?: T` | `T`, and `x` is left out of `required` |
+| `A \| B` (objects or mixed primitives) | `{ "anyOf": [A, B] }` |
+| object literals, interfaces, classes from your code | `{ "type": "object", "properties": …, "required": … }` |
+| `Date`, `Map`, `Set`, DOM types, anything from a library, `any`, `unknown`, `Record<string, T>` | a **bare `{}`** |
+| `get x(): T` | `x: T` — getters are members |
+| `get "users.*.ageCategory"(): string` | injected as `users.items.properties.ageCategory` — a path getter is a member at the path it computes |
+| methods, function-valued properties, `$`-prefixed keys (`$watch`, `$commandTokens`, …) | dropped |
+| nesting deeper than `--max-depth` | a bare `{}` |
+
+The bare `{}` matters: the validator treats it as *unknown* and stays silent below it, whereas a typed object that lacks a member is *nonexistent* and an **error**. A `Date` or a `Record<string, unknown>` therefore never produces false errors for the paths under it.
+
+## Library API
+
+```ts
+import { generateStateSchema, buildManifest, compareStateSchema } from "@wcstack/typescript";
+
+const { schema, warnings } = generateStateSchema("src/state.ts");   // { tsconfig?, maxDepth? }
+const manifest = buildManifest("default", schema /*, existingManifestObject */);
+const result = compareStateSchema(JSON.stringify(manifest), "default", schema); // { kind: "same" } | { kind: "differs", changes } | …
+```
+
+`loadStateFile` / `stateTypeToSchema` expose the two halves (compiler program, type → schema) for tools that want to compose them differently.
+
+## Where this fits
+
+- The validator side — discovery of the nearest `wcstack.manifest.json`, `wcs/path-nonexistent`, `wcs/path-type-mismatch` — is documented in [`@wcstack/lint`](../lint/README.md#declaring-a-state-contract-stateschema) and normatively in [`docs/wcstack-manifest-schema.md`](https://github.com/wcstack/wcstack/blob/main/docs/wcstack-manifest-schema.md).
+- The full TypeScript story for wcstack apps (typing `this` with `defineState`, this package, tag name maps, `wcs-tsc`) is collected in [`docs/typescript.md`](https://github.com/wcstack/wcstack/blob/main/docs/typescript.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -85,14 +85,20 @@ declare function generateStateSchema(file: string, options?: GenerateOptions): G
  *
  * The manifest is a **derived artifact** (D9): the TypeScript type is the source
  * of truth, `wcs-schema emit` writes the manifest, and `wcs-schema check`
- * detects drift between the two in CI. `--merge` replaces exactly one
- * `states[name].stateSchema` and keeps everything else (other states, filters,
- * listContexts) — a hand-written schema for the same state does not survive,
- * by design: there is no implicit merge in the sidecar spec (§5).
+ * detects drift between the two in CI.
+ *
+ * v2 (schemaVersion 2): the application namespace carries a **single**
+ * `stateSchema` — one state tree per root, no name dimension
+ * (docs/state-mount-design.md D15). A volume (`<wcs-state mount="path">`)
+ * contributes a **subtree**: `--mount=<path>` merges the module's schema under
+ * that path inside the single `stateSchema`. `--merge` keeps everything else in
+ * an existing manifest (filters, listContexts); a hand-written schema for the
+ * same slot does not survive, by design: there is no implicit merge in the
+ * sidecar spec (§5).
  */
 
 declare const APPLICATION_MANIFEST_FILENAME = "wcstack.manifest.json";
-declare const SCHEMA_VERSION = 1;
+declare const SCHEMA_VERSION = 2;
 declare const APPLICATION_NAMESPACE = "wcstack.application";
 interface ApplicationManifest {
     schemaVersion: number;
@@ -100,9 +106,7 @@ interface ApplicationManifest {
     manifestExtensions: {
         [APPLICATION_NAMESPACE]: {
             version: number;
-            states?: Record<string, {
-                stateSchema: JsonSchemaNode;
-            }>;
+            stateSchema?: JsonSchemaNode;
             [key: string]: unknown;
         };
         [namespace: string]: unknown;
@@ -110,12 +114,23 @@ interface ApplicationManifest {
     [key: string]: unknown;
 }
 /**
- * Create the manifest object for one state, or graft the state into `existing`
- * (a parsed manifest object; envelope fields are filled in when absent).
+ * Create the manifest object for the state tree, or graft into `existing`
+ * (a parsed manifest object; envelope fields are normalized to v2 — a v1
+ * manifest's `states` map does not survive, its replacement is exactly this
+ * regeneration path).
+ *
+ * `mountPath === null` replaces the whole `stateSchema`; a mount path merges
+ * the schema as a subtree at that path (intermediate object nodes are created).
  */
-declare function buildManifest(stateName: string, schema: JsonSchemaNode, existing?: unknown): ApplicationManifest;
-/** Read `states[name].stateSchema` from a parsed manifest object, or undefined. */
-declare function readStateSchema(manifest: unknown, stateName: string): unknown;
+declare function buildManifest(mountPath: string | null, schema: JsonSchemaNode, existing?: unknown): ApplicationManifest;
+/** Read the single `stateSchema` from a parsed manifest object, or undefined. */
+declare function readStateSchema(manifest: unknown): unknown;
+/**
+ * True for a v1-shaped manifest (`schemaVersion: 1` or a `states` map in the
+ * application namespace). `check` uses it to point at the regeneration path
+ * instead of reporting a confusing "missing stateSchema".
+ */
+declare function isV1Manifest(manifest: unknown): boolean;
 /** JSON with object keys sorted at every level — the canonical form used for comparison. */
 declare function stableStringify(value: unknown): string;
 type SchemaComparison = {
@@ -125,16 +140,19 @@ type SchemaComparison = {
     readonly changes: readonly string[];
 } | {
     readonly kind: "missing-state";
+} | {
+    readonly kind: "v1-manifest";
 } | {
     readonly kind: "broken";
     readonly message: string;
 };
 /**
- * Compare the schema generated from the type with the one stored in `manifestText`.
+ * Compare the schema generated from the type with the one stored in `manifestText`
+ * (the whole tree, or the subtree at `mountPath`).
  * `changes` lists JSON pointers: `+ ptr` (only in generated), `- ptr` (only in
  * manifest), `~ ptr` (both, different value).
  */
-declare function compareStateSchema(manifestText: string, stateName: string, generated: JsonSchemaNode): SchemaComparison;
+declare function compareStateSchema(manifestText: string, mountPath: string | null, generated: JsonSchemaNode): SchemaComparison;
 
 /**
  * schemaCore.ts — the validator core bundle (`dist/schema-core.cjs`, built from
@@ -173,5 +191,5 @@ declare function loadSchemaCore(): SchemaCore;
 
 declare const VERSION: string;
 
-export { APPLICATION_MANIFEST_FILENAME, APPLICATION_NAMESPACE, DEFAULT_COMPILER_OPTIONS, DEFAULT_MAX_DEPTH, SCHEMA_VERSION, VERSION, buildManifest, compareStateSchema, generateStateSchema, loadSchemaCore, loadStateFile, readStateSchema, resolveCompilerOptions, schemaCoreCandidates, stableStringify, stateTypeToSchema };
+export { APPLICATION_MANIFEST_FILENAME, APPLICATION_NAMESPACE, DEFAULT_COMPILER_OPTIONS, DEFAULT_MAX_DEPTH, SCHEMA_VERSION, VERSION, buildManifest, compareStateSchema, generateStateSchema, isV1Manifest, loadSchemaCore, loadStateFile, readStateSchema, resolveCompilerOptions, schemaCoreCandidates, stableStringify, stateTypeToSchema };
 export type { ApplicationManifest, GenerateOptions, GeneratedSchema, JsonSchemaNode, LoadStateOptions, LoadedState, SchemaComparison, SchemaCore, SchemaOptions, WcsDiagnostic };