@lt-three/love3 0.1.0 → 0.1.1

package/dist/tuning/model.js

@@ -2,25 +2,25 @@ import { parseTokenColor } from "./color.js";
 import { FONT_KEYS, FONT_TOKEN, MODES, RADIUS_ROLES, emptyTuning } from "./types.js";
 
 //#region src/tuning/model.ts
-/** 色のトークンを実際に持つモード。ブランド色は共通なので、ダークの指定は `light` に寄せる。 */
+/** The mode that actually holds a color token. Brand colors are common to both, so a dark specification is folded into `light`. */
 function modeOf(catalog, name, mode) {
 	return mode === "dark" && catalog.colors.find((color) => color.name === name)?.hasDark === false ? "light" : mode;
 }
-/** 既定のフォント値。 */
+/** The default font value. */
 function defaultFont(catalog, key) {
 	return catalog.defaults.light[FONT_TOKEN[key]] ?? "";
 }
-/** 役割ごとの角丸（px）。指定が無ければ既定（control 6・surface 10）。 */
+/** The radius (px) per role. Falls back to the default (control 6, surface 10) when unspecified. */
 function radiusPx(tuning, catalog, role) {
 	return tuning.radius[role] ?? catalog.radius[role];
 }
-/** 本文の行の高さ（px）。サイズに比例させる（既定の 14px / 22px の比）。 */
+/** The body line height (px). Proportional to the size (the ratio of the default 14px / 22px). */
 function bodyLineHeight(catalog, size) {
 	return Math.round(size * catalog.body.lineHeight / catalog.body.size);
 }
 /**
-* 既定と同じ値の項目を落として、同じ内容が 1 通りの形になるようにする（保存・エクスポート・比較の前に通す）。
-* 色は正規の形（小文字の `#rrggbb`）にそろえる。読めない色は落とさずそのまま残す（検証は `parseTuning` の仕事）。
+* Drops items equal to the defaults so that the same content has a single form (run before saving, exporting, and comparing).
+* Colors are aligned to the canonical form (lowercase `#rrggbb`). Unreadable colors are kept as they are (validation is the job of `parseTuning`).
 */
 function normalize(tuning, catalog) {
 	const out = emptyTuning();
@@ -50,18 +50,18 @@ function toCanonical(value, alpha) {
 	const parsed = parseTokenColor(value, { alpha });
 	return parsed.ok ? parsed.value : value;
 }
-/** 既定と同じ（差分が無い）か。 */
+/** Whether it equals the defaults (has no difference). */
 function isEmpty(tuning, catalog) {
 	return countChanges(tuning, catalog) === 0;
 }
-/** 既定との差分の数（色・参照先・角丸・書体・影の項目ごとに 1）。 */
+/** The number of differences from the defaults (1 per item of color, reference, radius, typeface, and shadow). */
 function countChanges(tuning, catalog) {
 	const n = normalize(tuning, catalog);
 	return Object.keys(n.tokens.light).length + Object.keys(n.tokens.dark).length + Object.keys(n.semantic).length + Object.keys(n.radius).length + Object.keys(n.font).length + (n.shadow === "default" ? 0 : 1);
 }
 /**
-* トークンの実値。**参照（`var()`）をたどる**: セマンティックトークンは参照先（上書きがあればそれ、無ければ既定）の実値になる。
-* 参照先のランプを調整すれば、それを指すセマンティックトークンも変わる（実行時の CSS と同じ解決）。
+* The actual value of a token. **It follows references (`var()`)**: a semantic token takes the actual value of its target (the override if there is one, the default otherwise).
+* If you tune the ramp it refers to, the semantic tokens pointing at it change too (resolved the same way as the runtime CSS).
 */
 function colorValue(tuning, catalog, mode, name) {
 	const ref = (Object.hasOwn(tuning.semantic, name) ? tuning.semantic[name] : void 0) ?? (Object.hasOwn(catalog.semantic, name) ? catalog.semantic[name] : void 0);
@@ -73,7 +73,7 @@ function colorValue(tuning, catalog, mode, name) {
 	if (fallback === void 0) throw new Error(`未定義のトークン: --${name}`);
 	return fallback;
 }
-/** 全トークン（色・書体・調整した角丸）の実値の表。調整を重ねた後の値で、`tokens` と同じ形。 */
+/** A table of the actual values of all tokens (color, typeface, tuned radius). The values after the tuning is applied, in the same shape as `tokens`. */
 function effectiveTokens(tuning, catalog) {
 	const out = {
 		light: {},

package/dist/tuning/native.d.ts

@@ -1,35 +1,35 @@
 import { Mode, Tuning, TuningCatalog } from "./types.js";
 //#region src/tuning/native.d.ts
 /**
- * ライト・ダークで**同じ値**のトークン（`.dark` で再定義しない）と、それを指すエイリアス。
- * react-native-css は、1 度しか宣言されない変数を**ビルド時にリテラルへ畳み込む**ので、`bg-action` などのクラスは
- * 実機で CSS 変数を引かず、**実行時の上書き（`toNativeVariables`）に追従しない**。TS から色を引く `useTokenColor` は追従する。
- * 一覧が `definition.ts` と食い違わないことは、`native/lib/tokens.test.ts` が見る。
+ * Tokens with the **same value** in light and dark (not redefined in `.dark`), and the aliases pointing at them.
+ * react-native-css **folds a variable declared only once into a literal at build time**, so classes such as `bg-action`
+ * do not read a CSS variable on a real device and **do not follow runtime overrides (`toNativeVariables`)**. `useTokenColor`, which reads colors from TS, does follow them.
+ * `native/lib/tokens.test.ts` checks that the list does not drift from `definition.ts`.
  */
 export declare const NATIVE_BUILD_FIXED_TOKENS: readonly ["action", "action-hover", "action-foreground", "primary", "primary-foreground", "ring", "sidebar-primary", "sidebar-primary-foreground", "sidebar-ring", "destructive-solid-foreground"];
 /**
- * ブランド色（`lt-three`・`lt-three-foreground`）。ライト・ダーク共通でビルド時に固定され、`bg-lt-three` などのクラスは
- * 実行時の上書きに追従しない（テーマで反転させないための仕様）。`NATIVE_BUILD_FIXED_TOKENS` とは別に持つのは、
- * `native/lib/tokens-check.ts` の畳み込み検査がブランド色を別扱いしているため（一覧の検査と食い違わせない）。
+ * The brand colors (`lt-three`, `lt-three-foreground`). They are common to light and dark and fixed at build time, so classes such as `bg-lt-three`
+ * do not follow runtime overrides (by design, so that they do not invert with the theme). They are kept apart from `NATIVE_BUILD_FIXED_TOKENS`
+ * because the folding check in `native/lib/tokens-check.ts` treats brand colors separately (so the list check does not drift).
  */
 export declare const NATIVE_BUILD_FIXED_BRAND_TOKENS: readonly ["lt-three", "lt-three-foreground"];
-/** 書体の値（CSS の font-family の並び）の先頭の名前。RN の `fontFamily` は 1 つの名前しか取らない。`var()` なら undefined。 */
+/** The first name in a typeface value (a CSS font-family list). RN's `fontFamily` takes only one name. undefined for `var()`. */
 export declare function firstFontFamily(value: string): string | undefined;
 /**
- * native に配る CSS 変数（react-native-css の `VariableContextProvider` の `value`）。指定したモードの、**既定と違うものだけ**。
- * - 色のトークン: 実効値（セマンティックの参照も解決した値）。ランプの変更に依存するセマンティックトークンも、同じ変更の下で
- *   別のリテラルとして載せる（react-native-web では `--card: var(--raised)` が `:root` で解決済みで、ランプの上書きだけでは追従しないため）
- * - 角丸（`--radius-control` / `--radius-surface`）: px
- * - 書体（`--font-geist` など）: 先頭の名前だけ
+ * The CSS variables handed to native (the `value` of react-native-css's `VariableContextProvider`). For the given mode, **only those that differ from the defaults**.
+ * - Color tokens: effective values (with semantic references resolved). Semantic tokens that depend on a changed ramp are also emitted
+ *   as separate literals under the same change (in react-native-web, `--card: var(--raised)` is already resolved at `:root` and does not follow an override of the ramp alone)
+ * - Radius (`--radius-control` / `--radius-surface`): px
+ * - Typeface (`--font-geist` and so on): only the first name
  *
- * **実機で効くのは、ライト・ダークで値が違う色のトークンを使うクラス（`bg-card` など。実機ではランプへの参照になる）と書体**。
- * 角丸・本文サイズはビルド時にリテラルへ畳み込まれ、`NATIVE_BUILD_FIXED_TOKENS` の色のクラスも畳み込まれるので、実機では効かない
- * （react-native-web では CSS 変数なので効く）。何が効かないかは `nativeLimits` が返す。
+ * **What takes effect on a real device is classes that use color tokens with different values in light and dark (such as `bg-card`; on a real device they become references to the ramp) and the typeface**.
+ * Radius and body size are folded into literals at build time, and the color classes of `NATIVE_BUILD_FIXED_TOKENS` are folded too, so they have no effect on a real device
+ * (in react-native-web they are CSS variables and do take effect). `nativeLimits` returns what has no effect.
  */
 export declare function toNativeVariables(tuning: Tuning, catalog: TuningCatalog, mode: Mode): Record<`--${string}`, string>;
 /**
- * 調整のうち、**native の実機では実行時に効かない項目**の説明（日本語）。空なら全部効く（react-native-web では全部効く）。
- * 調整の画面に出して、「効かないのは仕様」と分かるようにする。値は JSON に残るので、web で読めば効く。
+ * Descriptions (in Japanese) of the tuning items that **have no effect at runtime on a real native device**. Empty means everything takes effect (everything does in react-native-web).
+ * They are shown on the tuning screen so that it is clear the lack of effect is by design. The values stay in the JSON, so they take effect when read on web.
  */
 export declare function nativeLimits(tuning: Tuning, catalog: TuningCatalog): string[];
 //#endregion

package/dist/tuning/native.js

@@ -3,10 +3,10 @@ import { effectiveTokens, normalize } from "./model.js";
 
 //#region src/tuning/native.ts
 /**
-* ライト・ダークで**同じ値**のトークン（`.dark` で再定義しない）と、それを指すエイリアス。
-* react-native-css は、1 度しか宣言されない変数を**ビルド時にリテラルへ畳み込む**ので、`bg-action` などのクラスは
-* 実機で CSS 変数を引かず、**実行時の上書き（`toNativeVariables`）に追従しない**。TS から色を引く `useTokenColor` は追従する。
-* 一覧が `definition.ts` と食い違わないことは、`native/lib/tokens.test.ts` が見る。
+* Tokens with the **same value** in light and dark (not redefined in `.dark`), and the aliases pointing at them.
+* react-native-css **folds a variable declared only once into a literal at build time**, so classes such as `bg-action`
+* do not read a CSS variable on a real device and **do not follow runtime overrides (`toNativeVariables`)**. `useTokenColor`, which reads colors from TS, does follow them.
+* `native/lib/tokens.test.ts` checks that the list does not drift from `definition.ts`.
 */
 const NATIVE_BUILD_FIXED_TOKENS = [
 	"action",
@@ -21,27 +21,27 @@ const NATIVE_BUILD_FIXED_TOKENS = [
 	"destructive-solid-foreground"
 ];
 /**
-* ブランド色（`lt-three`・`lt-three-foreground`）。ライト・ダーク共通でビルド時に固定され、`bg-lt-three` などのクラスは
-* 実行時の上書きに追従しない（テーマで反転させないための仕様）。`NATIVE_BUILD_FIXED_TOKENS` とは別に持つのは、
-* `native/lib/tokens-check.ts` の畳み込み検査がブランド色を別扱いしているため（一覧の検査と食い違わせない）。
+* The brand colors (`lt-three`, `lt-three-foreground`). They are common to light and dark and fixed at build time, so classes such as `bg-lt-three`
+* do not follow runtime overrides (by design, so that they do not invert with the theme). They are kept apart from `NATIVE_BUILD_FIXED_TOKENS`
+* because the folding check in `native/lib/tokens-check.ts` treats brand colors separately (so the list check does not drift).
 */
 const NATIVE_BUILD_FIXED_BRAND_TOKENS = ["lt-three", "lt-three-foreground"];
-/** 書体の値（CSS の font-family の並び）の先頭の名前。RN の `fontFamily` は 1 つの名前しか取らない。`var()` なら undefined。 */
+/** The first name in a typeface value (a CSS font-family list). RN's `fontFamily` takes only one name. undefined for `var()`. */
 function firstFontFamily(value) {
 	const first = value.split(",")[0]?.trim() ?? "";
 	if (first === "" || first.startsWith("var(")) return void 0;
 	return first.replace(/^["']|["']$/g, "");
 }
 /**
-* native に配る CSS 変数（react-native-css の `VariableContextProvider` の `value`）。指定したモードの、**既定と違うものだけ**。
-* - 色のトークン: 実効値（セマンティックの参照も解決した値）。ランプの変更に依存するセマンティックトークンも、同じ変更の下で
-*   別のリテラルとして載せる（react-native-web では `--card: var(--raised)` が `:root` で解決済みで、ランプの上書きだけでは追従しないため）
-* - 角丸（`--radius-control` / `--radius-surface`）: px
-* - 書体（`--font-geist` など）: 先頭の名前だけ
+* The CSS variables handed to native (the `value` of react-native-css's `VariableContextProvider`). For the given mode, **only those that differ from the defaults**.
+* - Color tokens: effective values (with semantic references resolved). Semantic tokens that depend on a changed ramp are also emitted
+*   as separate literals under the same change (in react-native-web, `--card: var(--raised)` is already resolved at `:root` and does not follow an override of the ramp alone)
+* - Radius (`--radius-control` / `--radius-surface`): px
+* - Typeface (`--font-geist` and so on): only the first name
 *
-* **実機で効くのは、ライト・ダークで値が違う色のトークンを使うクラス（`bg-card` など。実機ではランプへの参照になる）と書体**。
-* 角丸・本文サイズはビルド時にリテラルへ畳み込まれ、`NATIVE_BUILD_FIXED_TOKENS` の色のクラスも畳み込まれるので、実機では効かない
-* （react-native-web では CSS 変数なので効く）。何が効かないかは `nativeLimits` が返す。
+* **What takes effect on a real device is classes that use color tokens with different values in light and dark (such as `bg-card`; on a real device they become references to the ramp) and the typeface**.
+* Radius and body size are folded into literals at build time, and the color classes of `NATIVE_BUILD_FIXED_TOKENS` are folded too, so they have no effect on a real device
+* (in react-native-web they are CSS variables and do take effect). `nativeLimits` returns what has no effect.
 */
 function toNativeVariables(tuning, catalog, mode) {
 	const n = normalize(tuning, catalog);
@@ -60,8 +60,8 @@ function toNativeVariables(tuning, catalog, mode) {
 	return out;
 }
 /**
-* 調整のうち、**native の実機では実行時に効かない項目**の説明（日本語）。空なら全部効く（react-native-web では全部効く）。
-* 調整の画面に出して、「効かないのは仕様」と分かるようにする。値は JSON に残るので、web で読めば効く。
+* Descriptions (in Japanese) of the tuning items that **have no effect at runtime on a real native device**. Empty means everything takes effect (everything does in react-native-web).
+* They are shown on the tuning screen so that it is clear the lack of effect is by design. The values stay in the JSON, so they take effect when read on web.
 */
 function nativeLimits(tuning, catalog) {
 	const n = normalize(tuning, catalog);

package/dist/tuning/schema.d.ts

@@ -1,14 +1,14 @@
 import { Tuning, TuningCatalog } from "./types.js";
 import { z } from "zod";
 //#region src/tuning/schema.d.ts
-/** エクスポート・保存の形式の名前とバージョン。形を変えたら `VERSION` を上げる。 */
+/** The name and version of the export and save format. Bump `VERSION` when the shape changes. */
 export declare const FORMAT = "love3-tuning";
 export declare const VERSION = 1;
-/** 保存先（localStorage）のキー。 */
+/** The key of the storage location (localStorage). */
 export declare const STORAGE_KEY = "love3-preview:tuning";
 /**
- * 形式の骨組み。**知らない項目は断る**（`strictObject`）。トークン名・色の中身など、DS に依存する検査は `parseTuning` が足す。
- * 全部省略できる（既定との差分だけを書く）。
+ * The skeleton of the format. **Unknown fields are rejected** (`strictObject`). Checks that depend on the design system, such as token names and color contents, are added by `parseTuning`.
+ * Every field can be omitted (write only the difference from the defaults).
  */
 declare const envelope: z.ZodObject<{
   format: z.ZodLiteral<"love3-tuning">;
@@ -35,13 +35,13 @@ declare const envelope: z.ZodObject<{
   }>>;
 }, z.core.$strict>;
 type Envelope = z.output<typeof envelope>;
-/** 取り込む JSON の大きさの上限（バイト）。貼り付け・ファイルとも。 */
+/** The upper limit of the size of an imported JSON (bytes), for both pasting and files. */
 export declare const MAX_IMPORT_BYTES: number;
-/** 1 つの表（`tokens.light` / `tokens.dark` / `semantic`）の項目数の上限。調整できる名前は 50 に満たない。 */
+/** The upper limit of the number of entries in one table (`tokens.light` / `tokens.dark` / `semantic`). There are fewer than 50 names that can be tuned. */
 export declare const MAX_ENTRIES = 200;
-/** 断る理由を、ここまで並べる（残りは「ほか N 件」）。 */
+/** Lists rejection reasons up to this many (the rest become "N more"). */
 export declare const MAX_REASONS = 20;
-/** 取り込もうとしている文字が、上限（`MAX_IMPORT_BYTES`）を超えるか。 */
+/** Whether the text being imported exceeds the limit (`MAX_IMPORT_BYTES`). */
 export declare function tooLarge(text: string): boolean;
 export declare const TOO_LARGE_REASON = "大きすぎます（256 KB まで）";
 export declare function fontProblem(value: string): string | undefined;
@@ -53,17 +53,17 @@ export type ParseResult = {
   reasons: string[];
 };
 /**
- * エクスポートの JSON（文字列）を読んで検証する。**1 つでも不正なら全体を断る（部分適用しない）**。
- * 断る理由は、見つけたものを全部、項目の場所つきの日本語で返す。
+ * Reads and validates an exported JSON (a string). **If anything is invalid, the whole input is rejected (no partial application).**
+ * The rejection reasons are all the problems found, in Japanese, each with the location of the item.
  *
- * 断るもの: JSON として読めない・`format` / `version` が違う・知らない項目・未知のトークン名（`--名前`）・
- * 不正な色・ライト・ダーク共通のトークン（ブランド色）のダークの指定・未知のセマンティックトークン・選べない参照先・
- * 範囲外の角丸と本文サイズ・差し込めない書体。成功したら、既定と同じ項目を落とした形（`normalize`）で返す。
+ * What is rejected: unreadable JSON, a wrong `format` / `version`, unknown fields, unknown token names (`--name`),
+ * invalid colors, a dark specification for a token common to light and dark (brand colors), unknown semantic tokens, unselectable reference targets,
+ * out-of-range radius and body size, and typefaces that cannot be injected. On success, it returns the form with items equal to the defaults dropped (`normalize`).
  */
 export declare function parseTuning(text: string, catalog: TuningCatalog): ParseResult;
-/** 差分だけのエクスポート用オブジェクト（空の節は省く）。 */
+/** The object for export containing only the difference (empty sections are omitted). */
 export declare function toExportObject(tuning: Tuning, catalog: TuningCatalog): Record<string, unknown>;
-/** エクスポート・保存の JSON（既定との差分だけ。整形つき）。 */
+/** The JSON for export and saving (only the difference from the defaults; pretty-printed). */
 export declare function toJson(tuning: Tuning, catalog: TuningCatalog): string;
 //#endregion
 export type { Envelope };

package/dist/tuning/schema.js

@@ -5,17 +5,17 @@ import { normalize } from "./model.js";
 import { z } from "zod";
 
 //#region src/tuning/schema.ts
-/** エクスポート・保存の形式の名前とバージョン。形を変えたら `VERSION` を上げる。 */
+/** The name and version of the export and save format. Bump `VERSION` when the shape changes. */
 const FORMAT = "love3-tuning";
 const VERSION = 1;
-/** 保存先（localStorage）のキー。 */
+/** The key of the storage location (localStorage). */
 const STORAGE_KEY = "love3-preview:tuning";
 const colorMap = z.record(z.string(), z.string());
 const radiusPx = z.number().min(0, { error: "角丸は 0 以上です" }).max(64, { error: `角丸は ${64}px 以下です` });
 const fontValue = z.string();
 /**
-* 形式の骨組み。**知らない項目は断る**（`strictObject`）。トークン名・色の中身など、DS に依存する検査は `parseTuning` が足す。
-* 全部省略できる（既定との差分だけを書く）。
+* The skeleton of the format. **Unknown fields are rejected** (`strictObject`). Checks that depend on the design system, such as token names and color contents, are added by `parseTuning`.
+* Every field can be omitted (write only the difference from the defaults).
 */
 const envelope = z.strictObject({
 	format: z.literal(FORMAT, { error: (issue) => `format は "${FORMAT}" にしてください（実際: ${show(issue.input)}）` }),
@@ -44,26 +44,26 @@ const envelope = z.strictObject({
 function show(value) {
 	return typeof value === "string" ? `"${value}"` : JSON.stringify(value) ?? String(value);
 }
-/** 取り込む JSON の大きさの上限（バイト）。貼り付け・ファイルとも。 */
+/** The upper limit of the size of an imported JSON (bytes), for both pasting and files. */
 const MAX_IMPORT_BYTES = 262144;
-/** 1 つの表（`tokens.light` / `tokens.dark` / `semantic`）の項目数の上限。調整できる名前は 50 に満たない。 */
+/** The upper limit of the number of entries in one table (`tokens.light` / `tokens.dark` / `semantic`). There are fewer than 50 names that can be tuned. */
 const MAX_ENTRIES = 200;
-/** 断る理由を、ここまで並べる（残りは「ほか N 件」）。 */
+/** Lists rejection reasons up to this many (the rest become "N more"). */
 const MAX_REASONS = 20;
 const BYTE_ENCODER = new TextEncoder();
-/** 取り込もうとしている文字が、上限（`MAX_IMPORT_BYTES`）を超えるか。 */
+/** Whether the text being imported exceeds the limit (`MAX_IMPORT_BYTES`). */
 function tooLarge(text) {
 	return text.length > 262144 || BYTE_ENCODER.encode(text).length > 262144;
 }
 const TOO_LARGE_REASON = `大きすぎます（${MAX_IMPORT_BYTES / 1024} KB まで）`;
 /**
-* 書体の値（CSS の font-family）の**許可リスト**。次の部品を、カンマ区切りに並べたものだけを通す:
-* - 閉じたクォート付きの名前（`"Geist Variable"` / `'Yu Gothic'`）。中に `\` `;` `{` `}` `<` `>` と改行は置かない
-* - 素の名前（文字・数字・`-`・`_`・空白。非 ASCII も可。`sans-serif` `ui-monospace` など）
-* - `var(--font-…)` の参照（`--font-mono: var(--font-geist-mono)` のような既定の形）
+* An **allowlist** for typeface values (CSS font-family). Only comma-separated lists of the following parts pass:
+* - Names with closed quotes (`"Geist Variable"` / `'Yu Gothic'`). `\`, `;`, `{`, `}`, `<`, `>`, and newlines are not allowed inside
+* - Bare names (letters, digits, `-`, `_`, and spaces; non-ASCII is allowed too; `sans-serif`, `ui-monospace`, and so on)
+* - `var(--font-…)` references (the default form such as `--font-mono: var(--font-geist-mono)`)
 *
-* **クォートの外の括弧（`(` `)` `[` `]`）と閉じていないクォートは断る**。通すと、`;` や `}` が括弧・引用符に飲まれて、
-* 後ろの宣言や `.dark {}` のブロック全体が消える（`Arial(` の再現）。理由を返す（安全なら undefined）。
+* **Brackets outside quotes (`(` `)` `[` `]`) and unclosed quotes are rejected.** If they were let through, a `;` or `}` would be swallowed by the bracket or quote,
+* and the following declarations or the whole `.dark {}` block would disappear (reproduced with `Arial(`). Returns the reason (undefined if safe).
 */
 function unreadable(value, index) {
 	return `書体の「${value.slice(index, index + 12).trim()}」から先を読めません。使えるのは、閉じたクォート付きの名前・素の名前（英数字・-・_・空白）・カンマ・var(--font-…) だけです（括弧 ( ) [ ] ; や閉じていない引用符は使えません）`;
@@ -86,12 +86,12 @@ function fontProblem(value) {
 	}
 }
 /**
-* エクスポートの JSON（文字列）を読んで検証する。**1 つでも不正なら全体を断る（部分適用しない）**。
-* 断る理由は、見つけたものを全部、項目の場所つきの日本語で返す。
+* Reads and validates an exported JSON (a string). **If anything is invalid, the whole input is rejected (no partial application).**
+* The rejection reasons are all the problems found, in Japanese, each with the location of the item.
 *
-* 断るもの: JSON として読めない・`format` / `version` が違う・知らない項目・未知のトークン名（`--名前`）・
-* 不正な色・ライト・ダーク共通のトークン（ブランド色）のダークの指定・未知のセマンティックトークン・選べない参照先・
-* 範囲外の角丸と本文サイズ・差し込めない書体。成功したら、既定と同じ項目を落とした形（`normalize`）で返す。
+* What is rejected: unreadable JSON, a wrong `format` / `version`, unknown fields, unknown token names (`--name`),
+* invalid colors, a dark specification for a token common to light and dark (brand colors), unknown semantic tokens, unselectable reference targets,
+* out-of-range radius and body size, and typefaces that cannot be injected. On success, it returns the form with items equal to the defaults dropped (`normalize`).
 */
 function parseTuning(text, catalog) {
 	if (tooLarge(text)) return {
@@ -194,7 +194,7 @@ function parseTuning(text, catalog) {
 		tuning: normalize(tuning, catalog)
 	};
 }
-/** 差分だけのエクスポート用オブジェクト（空の節は省く）。 */
+/** The object for export containing only the difference (empty sections are omitted). */
 function toExportObject(tuning, catalog) {
 	const n = normalize(tuning, catalog);
 	const out = {
@@ -211,11 +211,11 @@ function toExportObject(tuning, catalog) {
 	if (n.shadow !== "default") out.shadow = n.shadow;
 	return out;
 }
-/** エクスポート・保存の JSON（既定との差分だけ。整形つき）。 */
+/** The JSON for export and saving (only the difference from the defaults; pretty-printed). */
 function toJson(tuning, catalog) {
 	return JSON.stringify(toExportObject(tuning, catalog), null, 2);
 }
-/** 読んだ JSON の、決まった道筋にある表（オブジェクト）。無ければ undefined。 */
+/** The table (object) at a given path in the parsed JSON. undefined if absent. */
 function rawTable(json, path) {
 	let current = json;
 	for (const key of path) {

package/dist/tuning/types.d.ts

@@ -1,36 +1,36 @@
 //#region src/tuning/types.d.ts
-/** ライト・ダーク。 */
+/** Light and dark. */
 export type Mode = "light" | "dark";
 export declare const MODES: readonly Mode[];
 /**
- * 角丸の役割（`--radius-control` / `--radius-surface`。部品は `rounded-control` / `rounded-surface` を使う）。
- * - `control`: 操作する小さな要素（Button・入力・Select のトリガー・Checkbox・Badge・メニューの項目ほか）
- * - `surface`: 面・入れ物（Card・Dialog・Sheet・Popover・Alert・Tooltip・メニューの入れ物ほか）
+ * Radius roles (`--radius-control` / `--radius-surface`; components use `rounded-control` / `rounded-surface`).
+ * - `control`: small interactive elements (Button, inputs, the Select trigger, Checkbox, Badge, menu items, and so on)
+ * - `surface`: surfaces and containers (Card, Dialog, Sheet, Popover, Alert, Tooltip, menu containers, and so on)
  */
 export declare const RADIUS_ROLES: readonly ["control", "surface"];
 export type RadiusRole = (typeof RADIUS_ROLES)[number];
-/** 角丸（px）の上限。スライダも数値の入力も、ここまで。 */
+/** The upper limit of the radius (px). Both the slider and numeric input stop here. */
 export declare const RADIUS_MAX = 64;
-/** 書体のキー（`--font-geist` / `--font-geist-mono` / `--font-jp`）。 */
+/** Typeface keys (`--font-geist` / `--font-geist-mono` / `--font-jp`). */
 export declare const FONT_KEYS: readonly ["geist", "geistMono", "jp"];
 export type FontKey = (typeof FONT_KEYS)[number];
 export declare const FONT_TOKEN: Readonly<Record<FontKey, string>>;
-/** 本文サイズ（px）の範囲。 */
+/** The range of the body size (px). */
 export declare const BODY_SIZE_MIN = 8;
 export declare const BODY_SIZE_MAX = 32;
 /**
- * 影の preset。`default` は love3 の既定（`--shadow-color` を使う淡い影）。`none` は全ての影を消す。
- * `preset` は Tailwind の既定の影に差し替える。
+ * Shadow presets. `default` is the love3 default (soft shadows using `--shadow-color`). `none` removes all shadows.
+ * `preset` swaps in Tailwind's default shadows.
  */
 export type ShadowPreset = "default" | "none" | "preset";
 /**
- * 調整の内容。**既定との差分だけ**を持つ（空 = 既定どおり）。保存・エクスポートの正本と同じ形。
+ * The content of a tuning. It holds **only the difference from the defaults** (empty = the defaults as they are). The same shape as the canonical form for saving and exporting.
  *
- * - `tokens`: 色のトークンの上書き。ライト・ダーク別。ブランド色（`lt-three*`）は共通なので `light` にだけ持つ
- * - `radius`: 役割ごとの角丸（px）。`control`（操作する小さな要素）と `surface`（面・入れ物）。無ければ既定（`TuningCatalog.radius`）
- * - `semantic`: セマンティックトークン（`background` など）の参照先（ランプ・状態・ブランドの名前）
- * - `font`: 書体（CSS の font-family の値）と本文サイズ（px）
- * - `shadow`: 影の preset（既定は `default` = love3 の淡い影）
+ * - `tokens`: overrides of color tokens, per light and dark. Brand colors (`lt-three*`) are common to both, so they are held only in `light`
+ * - `radius`: the radius (px) per role. `control` (small interactive elements) and `surface` (surfaces and containers). Falls back to the default (`TuningCatalog.radius`) when absent
+ * - `semantic`: what the semantic tokens (`background` and so on) refer to (names of ramp, state, and brand tokens)
+ * - `font`: the typeface (a CSS font-family value) and the body size (px)
+ * - `shadow`: the shadow preset (the default is `default` = the love3 soft shadows)
  */
 export interface Tuning {
   tokens: Record<Mode, Record<string, string>>;
@@ -42,31 +42,31 @@ export interface Tuning {
   shadow: ShadowPreset;
 }
 export declare function emptyTuning(): Tuning;
-/** 色のトークンの区分。 */
+/** The groups of color tokens. */
 export type ColorGroup = "ramp" | "action" | "brand" | "state" | "chart";
 export interface ColorToken {
   name: string;
   group: ColorGroup;
-  /** ダークで別の値を持てるか。ブランド色は共通なので持たない。 */
+  /** Whether it can have a separate value in dark. Brand colors are common to both, so they do not. */
   hasDark: boolean;
-  /** 半透明を許すか（scrim）。それ以外は不透明な `#rrggbb` だけ。 */
+  /** Whether translucency is allowed (scrim). Everything else is an opaque `#rrggbb` only. */
   alpha: boolean;
 }
 /**
- * 調整の対象と既定値。DS から作る（`buildCatalog`）。ロジックはこの形だけを見るので、DS に依存せず Node でテストできる。
+ * What can be tuned, and the defaults. Built from the design system (`buildCatalog`). The logic looks only at this shape, so it does not depend on the design system and can be tested in Node.
  */
 export interface TuningCatalog {
-  /** 既定の実値（`var()` を解決したもの。love3 の `tokens`）。 */
+  /** The default actual values (with `var()` resolved; the love3 `tokens`). */
   defaults: Readonly<Record<Mode, Readonly<Record<string, string>>>>;
-  /** 色のトークン（生のランプ・主操作・ブランド・状態・チャート）。定義の順。 */
+  /** The color tokens (raw ramp, primary action, brand, state, chart), in definition order. */
   colors: readonly ColorToken[];
-  /** セマンティックトークン名 → 既定の参照先（`background` → `paper`）。定義の順。 */
+  /** Semantic token name → default reference (`background` → `paper`), in definition order. */
   semantic: Readonly<Record<string, string>>;
-  /** セマンティックの参照先に選べる名前（不透明な色のトークン）。 */
+  /** The names that can be chosen as the target of a semantic reference (opaque color tokens). */
   refOptions: readonly string[];
-  /** 役割ごとの角丸の既定（px）。CSS の `@theme`（`--radius-control` / `--radius-surface`）から読む。 */
+  /** The default radius (px) per role. Read from the CSS `@theme` (`--radius-control` / `--radius-surface`). */
   radius: Readonly<Record<RadiusRole, number>>;
-  /** 本文サイズの既定（px）と行の高さ（px）。 */
+  /** The default body size (px) and line height (px). */
   body: {
     size: number;
     lineHeight: number;

package/dist/tuning/types.js

@@ -1,14 +1,14 @@
 //#region src/tuning/types.ts
 const MODES = ["light", "dark"];
 /**
-* 角丸の役割（`--radius-control` / `--radius-surface`。部品は `rounded-control` / `rounded-surface` を使う）。
-* - `control`: 操作する小さな要素（Button・入力・Select のトリガー・Checkbox・Badge・メニューの項目ほか）
-* - `surface`: 面・入れ物（Card・Dialog・Sheet・Popover・Alert・Tooltip・メニューの入れ物ほか）
+* Radius roles (`--radius-control` / `--radius-surface`; components use `rounded-control` / `rounded-surface`).
+* - `control`: small interactive elements (Button, inputs, the Select trigger, Checkbox, Badge, menu items, and so on)
+* - `surface`: surfaces and containers (Card, Dialog, Sheet, Popover, Alert, Tooltip, menu containers, and so on)
 */
 const RADIUS_ROLES = ["control", "surface"];
-/** 角丸（px）の上限。スライダも数値の入力も、ここまで。 */
+/** The upper limit of the radius (px). Both the slider and numeric input stop here. */
 const RADIUS_MAX = 64;
-/** 書体のキー（`--font-geist` / `--font-geist-mono` / `--font-jp`）。 */
+/** Typeface keys (`--font-geist` / `--font-geist-mono` / `--font-jp`). */
 const FONT_KEYS = [
 	"geist",
 	"geistMono",
@@ -19,7 +19,7 @@ const FONT_TOKEN = {
 	geistMono: "font-geist-mono",
 	jp: "font-jp"
 };
-/** 本文サイズ（px）の範囲。 */
+/** The range of the body size (px). */
 const BODY_SIZE_MIN = 8;
 const BODY_SIZE_MAX = 32;
 function emptyTuning() {

package/dist/web/analytics/line-chart.d.ts

@@ -2,19 +2,19 @@ import { ChartCommonProps, LineChartSharedProps } from "../../shared/analytics.j
 import { CSSProperties } from "react";
 //#region src/web/analytics/line-chart.d.ts
 export type LineChartProps = ChartCommonProps & LineChartSharedProps & {
-  /** 外側の要素に渡す style（native の `style: ViewStyle` に当たる）。 */
+  /** Style passed to the outer element (corresponds to native's `style: ViewStyle`). */
   style?: CSSProperties;
   className?: string;
-  /** 縦軸の目盛りとツールチップの値の整形（web の追加。native の `LineChart` は OS のチャートが整形する）。 */
+  /** Formatting of the y-axis ticks and the tooltip values (a web addition. Native's `LineChart` is formatted by the OS chart). */
   formatValue?: (value: number) => string;
-  /** データが空のときの文言（web の追加）。 */
+  /** Text shown when there is no data (a web addition). */
   emptyText?: string;
 };
 /**
- * 単一系列の折れ線。native の `analytics/line-chart` と同じ API（`shared/analytics.ts`）。**`data` と `formatValue` は参照を安定させて渡す**（`MultiLineChart` と同じ）。
- * 中身は 1 本の系列の `MultiLineChart`（凡例は出さない）。複数の系列を重ねるなら `MultiLineChart`。
+ * A single-series line chart. Same API as native's `analytics/line-chart` (`shared/analytics.ts`). **Pass `data` and `formatValue` with stable references** (same as `MultiLineChart`).
+ * Inside it is a `MultiLineChart` with one series (no legend). To overlay several series, use `MultiLineChart`.
  *
- * native の `LineChart` は iOS の SwiftUI Charts で、iOS 以外では `fallbackText` を出す。web は常に描くので `fallbackText` を持たない。
+ * Native's `LineChart` is iOS SwiftUI Charts, and shows `fallbackText` on anything other than iOS. Web always draws, so it has no `fallbackText`.
  */
 export declare function LineChart({ data, color, ...rest }: LineChartProps): import("react").JSX.Element;
 //#endregion

package/dist/web/analytics/line-chart.js

@@ -5,10 +5,10 @@ import { jsx } from "react/jsx-runtime";
 
 //#region src/web/analytics/line-chart.tsx
 /**
-* 単一系列の折れ線。native の `analytics/line-chart` と同じ API（`shared/analytics.ts`）。**`data` と `formatValue` は参照を安定させて渡す**（`MultiLineChart` と同じ）。
-* 中身は 1 本の系列の `MultiLineChart`（凡例は出さない）。複数の系列を重ねるなら `MultiLineChart`。
+* A single-series line chart. Same API as native's `analytics/line-chart` (`shared/analytics.ts`). **Pass `data` and `formatValue` with stable references** (same as `MultiLineChart`).
+* Inside it is a `MultiLineChart` with one series (no legend). To overlay several series, use `MultiLineChart`.
 *
-* native の `LineChart` は iOS の SwiftUI Charts で、iOS 以外では `fallbackText` を出す。web は常に描くので `fallbackText` を持たない。
+* Native's `LineChart` is iOS SwiftUI Charts, and shows `fallbackText` on anything other than iOS. Web always draws, so it has no `fallbackText`.
 */
 function LineChart({ data, color = "var(--chart-1)", ...rest }) {
 	const series = useMemo(() => [{

package/dist/web/analytics/metric-card.d.ts

@@ -2,17 +2,17 @@ import { MetricCardSharedProps } from "../../shared/analytics.js";
 import { ReactNode } from "react";
 //#region src/web/analytics/metric-card.d.ts
 export type MetricCardProps = Omit<MetricCardSharedProps, "label"> & {
-  /** 指標の名前。文字列のほか、ヘルプのトリガー付きの見出しなど要素も渡せる（native は文字列）。 */
+  /** Name of the metric. Besides a string you can pass an element, such as a heading with a help trigger (native takes a string). */
   label: ReactNode;
 };
 /**
- * 面付きの単一指標（ラベル + 大型の等幅数値 + 補助）。native の `analytics/metric-card` と同じ API（`shared/analytics.ts`）。
- * raised 面 + 1px の薄い枠 + surface 角丸で、影は付けない。
+ * A single metric on a surface (label + a large monospaced number + supporting text). Same API as native's `analytics/metric-card` (`shared/analytics.ts`).
+ * A raised surface + a thin 1px border + the surface corner radius, with no shadow.
  *
- * 中身は `<dl>`（ラベルが dt・値と補助が dd）で、それ自体で成り立つ（グリッドの親は `<div>` でよい）。
- * 値は 1 行に収め、入りきらないときは省略する（折り返さない）。
+ * Inside it is a `<dl>` (the label is a dt; the value and the supporting text are dd), and it stands on its own (a grid parent can be a `<div>`).
+ * The value stays on one line and is truncated when it does not fit (it does not wrap).
  *
- * `trend` が正なら値を `state-success`、負なら `state-error` で塗る。**色だけで伝えない**ので、増減は `value` に符号を含める。
+ * When `trend` is positive the value is coloured `state-success`; when negative, `state-error`. **Meaning is not conveyed by colour alone**, so put the sign in `value`.
  */
 export declare function MetricCard({ label, value, subValue, trend, className }: MetricCardProps): import("react").JSX.Element;
 //#endregion

package/dist/web/analytics/metric-card.js

@@ -3,13 +3,13 @@ import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/web/analytics/metric-card.tsx
 /**
-* 面付きの単一指標（ラベル + 大型の等幅数値 + 補助）。native の `analytics/metric-card` と同じ API（`shared/analytics.ts`）。
-* raised 面 + 1px の薄い枠 + surface 角丸で、影は付けない。
+* A single metric on a surface (label + a large monospaced number + supporting text). Same API as native's `analytics/metric-card` (`shared/analytics.ts`).
+* A raised surface + a thin 1px border + the surface corner radius, with no shadow.
 *
-* 中身は `<dl>`（ラベルが dt・値と補助が dd）で、それ自体で成り立つ（グリッドの親は `<div>` でよい）。
-* 値は 1 行に収め、入りきらないときは省略する（折り返さない）。
+* Inside it is a `<dl>` (the label is a dt; the value and the supporting text are dd), and it stands on its own (a grid parent can be a `<div>`).
+* The value stays on one line and is truncated when it does not fit (it does not wrap).
 *
-* `trend` が正なら値を `state-success`、負なら `state-error` で塗る。**色だけで伝えない**ので、増減は `value` に符号を含める。
+* When `trend` is positive the value is coloured `state-success`; when negative, `state-error`. **Meaning is not conveyed by colour alone**, so put the sign in `value`.
 */
 function MetricCard({ label, value, subValue, trend, className }) {
 	const tone = trend === void 0 || trend === 0 ? void 0 : trend > 0 ? "up" : "down";