@frdt/frdt 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rheniumNV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @frdt/frdt
+
+Resonite の `.brson`（中身は FrDT 形式）を、JSON へ展開せずに読み、編集し、書き戻す Node.js パッケージです。中身は Rust クレート [frdt](https://crates.io/crates/frdt) で、TypeScript の型が付いています。
+
+npm では、短い名前 `frdt` が既存のパッケージと似すぎているとして使えなかったため、組織 `frdt` のスコープ付きの `@frdt/frdt` で出しています。環境ごとのネイティブ版（`@frdt/binding-<platform>`）は npm が自動で選んで入れるので、直接入れる必要はありません。
+
+Read and edit Resonite `.brson` (FrDT) files from Node.js without expanding them into JSON.
+
+```sh
+npm install @frdt/frdt
+```
+
+## どの環境で動くか
+
+インストールすると、次の環境ではネイティブ版が入り、それが使われます。
+
+- Windows x64
+- Linux x64（glibc と musl）
+- macOS arm64（Apple Silicon）
+
+それ以外の環境では、パッケージに同梱した WebAssembly 版が使われます。どちらでも API は同じで、呼び出し側で選ぶ必要はありません。ネイティブ版の方が速く動きます。どちらが読み込まれたかは `__napiBindingTarget`（`'native'` か `'wasm32-wasi'`）で分かります。
+
+Node.js は 20.19 以降の 20.x、22.13 以降の 22.x、23.5 以降が必要です。WebAssembly 版が使う `@napi-rs/wasm-runtime` と同じ範囲で、CI では 20、22、24 で両方の版を試しています。WebAssembly 版はスレッドを使うので、Node.js の `worker_threads` が使える環境で動きます。ブラウザは対象にしていません。
+
+## 使い方
+
+### 読む
+
+```ts
+import { readFileSync } from 'node:fs'
+import { Document, summarize } from '@frdt/frdt'
+
+const bytes = readFileSync('item.brson')
+
+// 展開せずに数える
+const s = summarize(bytes)
+console.log(`${s.slotCount} slots, ${s.componentCount} components`)
+
+// 開いて辿る
+const doc = Document.open(bytes)
+const root = doc.root()
+console.log(root.name(), doc.versionNumber())
+for (const child of root.children()) {
+  for (const c of child.components()) console.log(child.name(), c.typeName)
+}
+```
+
+### 編集して書き出す
+
+```ts
+import { writeFileSync } from 'node:fs'
+import { Document, type Value } from '@frdt/frdt'
+
+const str = (value: string): Value => ({ kind: 'string', value })
+
+const doc = Document.open(bytes)
+const panel = doc.addSlot(doc.root(), 'Panel')
+const { index } = doc.addComponent(panel, '[FrooxEngine]FrooxEngine.DynamicValueVariable<string>', null, [
+  { name: 'VariableName', value: str('App.Title') },
+  { name: 'Value', value: str('Hello') },
+])
+panel.setComponentValue(index, 'Value', str('Hello, Resonite'))
+panel.set('Name', str('TitlePanel'))
+
+writeFileSync('out.brson', doc.writeBrson())
+```
+
+### 別のファイルの部分木を、新しい木にまとめる
+
+```ts
+const part = Document.open(partBytes)
+const source = part.slotById(slotId)
+
+const out = Document.empty('Combined', part.versionNumber(), part.featureFlags())
+const imported = out.import(out.root(), [source])
+// 写した先の id は imported.newId(元の id) で引ける
+out.rebuildTypes()
+```
+
+## 値の形
+
+フィールドの値は `{ kind, value }` で渡し、受け取ります。
+
+| `kind` | `value` | Resonite での形 |
+| --- | --- | --- |
+| `'string'` | `string` | 文字列。参照は相手の id をこれで渡す |
+| `'int'` | `number` | int64。2^53 までは正確 |
+| `'float'` | `number` | double |
+| `'bool'` | `boolean` | 真偽値 |
+| `'float3'` | `number[]`（3つ） | double の配列 |
+| `'floatQ'` | `number[]`（4つ） | double の配列 |
+
+null は `null` です。
+
+## 考え方
+
+- **JSON を通さない。** 編集の実体は、展開した BSON 1枚と、スロットの位置を指す索引です。変えていない値はバイト列のままコピーします。
+- **知らないものを落とさない。** コンポーネントごとのスキーマは持たず、触ったフィールドだけを読み書きします。
+- **Resonite の形で書く。** 新しく書く値は、Resonite が保存するのと同じ形にします。
+
+`Slot` は、編集のあとも同じスロットを指したままです。外したスロットの `Slot` は、エラーを返します。失敗はすべて `Error` を投げます。
+
+## 対応している範囲
+
+- 圧縮は Brotli（FrDT の圧縮種別 `0x03`）です。LZ4 と LZMA は読みません。
+- BSON の日時型（`0x09`）は、まだ扱えません。
+- 参照かどうかは、文字列が文書内の id と一致するかで決めます。
+
+## 使われているところ
+
+もともとは、Resonite 向けの UI フレームワーク MirageX と、アイテム共有サービス [UniPocket](https://github.com/uni-pocket/uni-pocket) のために作りました。
+
+## 生成AI
+
+このパッケージのコードと文書は、生成AIの支援を受けて作成しています。
+
+## ライセンス
+
+MIT License。バイナリに含まれるライブラリのライセンスは `THIRD-PARTY-NOTICES.md` にあります。