logdraft

マニュアル生成器・サブアプリ連携の壁打ちメモ

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 をどう置くか(ゲーム詳細ページのボタン位置)

次のアクション

  1. ADR: TypeScript 採用と html-build 拡張
  2. ADR: サブドメイン間 URL ハンドオフプロトコル
  3. ADR: dicebear 型決定的アバター生成
  4. ADR: 判別共用体としての RuleBookIR
  5. html-build の esbuild 化 PoC