マニュアル生成器・サブアプリ連携の壁打ちメモ
blog.parlourite.com を実験ツールのホストにする方針と、html-build の TS 対応、dicebear 型アバターの設計についての壁打ち記録。
背景
ボードゲーム定義ファイル(DSL)から自然言語のルールブックを生成する試作機を blog 側で開発中。 本家 parlourite.com は本体のみを持ち、実験的ツールは blog.parlourite.com に置く分離方針を再確認。
検討した論点
1. 本家 → blog へのツール呼び出し方法
- リンクで飛ばす(推奨):
blog.parlourite.com/tools/rulebook/?spec=<id>@<version> - iframe 埋め込み: 高さ同期・テーマ共有・CORS で複雑化。却下
- postMessage + popup: アバター作成のような往復が必要な場合のみ採用
理由: サイト間の共通インターフェイスを URL + R2 に絞ることで、各ツールは独立に作れる。
2. R2 からゲーム定義を渡す
- 生 URL で渡す案 vs ID で渡して blog 側で解決する案
- 後者を採用: URL が短く、バケット構成を pariourite 側が知らなくてよい
- CORS: 公開バケットなら不要。非公開なら
Access-Control-Allow-Originを blog 側に限定
3. ソースコード露出
- バンドル = ソース隠蔽ではない
- minify + source map 非公開で実用上は十分
- 隠す価値があるのは DSL スキーマとゲーム定義だが、これらは R2 側にあり、そもそも公開 API として設計
- レンダラの実装を隠す価値は薄い。blog は見せる場所
4. アバターアプリ(dicebear 型)
- R2 保存不要、シード決定的生成 が正解
- blog.parlourite.com/tools/avatar/?seed=
で SVG を返す(実体はクライアントサイド生成) - parlourite 側は
<img src="...">で埋め込むだけ - DB には
avatar_seed: stringを 1 カラム追加するのみ
5. JSDoc vs TypeScript
- TS 採用を決定
- 理由: IR が判別共用体、モダンツールの既定が TS、html-build を TS 対応にすれば JSDoc の利点が消える
- 移行コストはモジュール数 8 の今が最小
- esbuild を html-build 内部に組み込めば
.tsを直接バンドル可能
6. html-build の TS 対応
- 既存の bundle.mjs を esbuild ベースに置換
.ts/.tsxを直接入力として受理- 型チェックは
tsc --noEmitを別コマンドで(ビルドと分離) @file/@import/@exportマーカーは コメントのまま維持(split ツールは変更不要)
未決事項
- html-build の esbuild 置換をいつやるか
- 既存 8 モジュールの
.ts移行を一括か段階か - source map を出すか(出さない推奨)
- blog 側のリンク UI をどう置くか(ゲーム詳細ページのボタン位置)
次のアクション
- ADR: TypeScript 採用と html-build 拡張
- ADR: サブドメイン間 URL ハンドオフプロトコル
- ADR: dicebear 型決定的アバター生成
- ADR: 判別共用体としての RuleBookIR
- html-build の esbuild 化 PoC