decisiondecided

サブドメイン間のツールハンドオフプロトコル

parlourite.com と blog.parlourite.com のツール連携は URL パラメータ + R2 に限定し、iframe 埋め込みは採用しない。ソース露出は minify で十分と判断する。

状況

  • 本家サイト parlourite.com はボードゲームプラットフォーム
  • blog.parlourite.com は読み物・実験ツールのサイト
  • マニュアル生成器・アバター生成器等を blog 側で開発中
  • 本家から「マニュアル表示」「アバター作成」を呼び出したい
  • ソースコードの露出を避けたいという気持ちがある
  • 両サイトの境界を曖昧にしたくない(アニメーション要求等で混乱を招く恐れ)

決定

両サイト間の連携は URL パラメータと R2(公開ストレージ)のみで行う。iframe は採用しない。

プロトコル仕様

マニュアル表示(片方向)

parlourite.com/play/<game>
→ [マニュアル] ボタン(<a target="_blank"> または window.open)
→ blog.parlourite.com/tools/rulebook/?spec=<game-id>@<version>
→ blog 側が R2 から定義ファイルを fetch
→ 表示
  • URL パラメータ: ?spec=<id>@<version>(短縮形を推奨)
  • R2 の URL を直接渡す代替案は却下(バケット構成が漏れる)
  • CORS: R2 が公開バケットなら不要

アバター作成(往復)

parlourite.com/profile/edit
→ [アバターを作る] ボタン
→ blog.parlourite.com/tools/avatar/?return=https://parlourite.com/profile/edit&seed=<current>
→ ユーザーが編集(クライアントサイド SVG 生成)
→ 保存時にリダイレクト:
https://parlourite.com/profile/edit#avatar=<new-seed>
→ parlourite 側が hash を拾って保存
  • 往復は return パラメータ + URL フラグメント(#)で行う
  • postMessage は使わない(popup 化する場合の将来オプション)
  • iframe は使わない

ソース露出への対応

  • minify する(バンドルサイズのため)
  • source map は出力しない(元の変数名・行番号を隠す)
  • 難読化(terser mangle 等)は行わない(過剰防衛)
  • 「バンドル = ソース隠蔽」は幻想であることを明記する

隠す価値があるのは:

  • DSL スキーマ → R2 側にあり、そもそも公開 API として設計している
  • ゲーム定義ファイル → 同上
  • レンダラ実装 → 隠しても価値は薄い。blog の役割は「見せる」こと

隠す価値があるが、それでも公開で問題ない:

  • フレーズ表(自然言語化の語彙)→ 公開した方がコミュニティ改善が入る

理由

なぜ iframe を採用しないか

問題iframe の場合リンクの場合
高さ同期postMessage 必須不要
テーマ CSSiframe 内で死ぬblog のテーマが活きる
CORS親子で設定必要R2 のみ
認証・Cookie分離問題関係なし
クリックジャッキング対策ヘッダ必須不要
アニメーション要求どちらのサイトの責務か曖昧明快(blog 側)

UX の劣化は「別タブが開く」程度。これを許容できないなら popup に格上げするが、それでも iframe は最後の手段。

なぜ URL パラメータ + R2 か

  • 両サイトが独立にデプロイできる
  • 境界が「URL で何を渡すか」に集約される
  • 将来のツール追加が独立して行える
  • ログ・監視が URL 単位で取れる

なぜ postMessage を今は使わないか

  • popup ブロッカーとの戦い
  • オリジン検証のコードが増える
  • まずリンクで始めて、UX に不満が出たら段階的に導入する

却下した代替案

A. iframe 埋め込み

上記の通り却下。

B. R2 の生 URL を渡す

  • 利点: blog 側に解決ロジックが不要
  • 却下理由: バケット構成が URL に露出する。将来バケットを分割した時に壊れる

C. 共通ライブラリを npm パッケージ化して両サイトで import

  • 利点: 一元管理
  • 却下理由: 今は不要。段階的に導入可能(packages/rulebook-core/ 案)。ADR-html-build-typescript の段階移行で対応する

D. サーバーサイドレンダリングでソース完全隠蔽

  • 利点: 本当に隠せる
  • 却下理由: blog の静的性が死ぬ。Cloudflare Pages の静的配信と衝突する。過剰防衛

影響

parlourite.com 側の追加

  • ゲーム詳細ページに <a> ボタンを 1 個追加
  • アバター編集ページに往復のリダイレクト受け取り処理
  • それ以外の変更なし

blog.parlourite.com 側の追加

  • /tools/rulebook/ のクエリパラメータ処理(?spec=)
  • /tools/avatar/ のクエリパラメータ処理(?return=, ?seed=)
  • R2 バケットへの fetch(CORS 設定)
  • それ以外の変更なし

セキュリティ

  • URL パラメータは公開情報のみ(ゲーム ID、シード文字列)
  • return パラメータはホワイトリスト検証(parlourite.com のみ許可)
  • シード文字列のサニタイズ(URL セーフ文字のみ)

Outcome (2026-10-18) — failed

  • Confidence at decision time: 0.8
  • 0 incidents
  • 0 days to recover

R2が公開というのがそもそも誤解。 gitのサブモジュールなどの同期を取ったり、SSOTが分からなくなる運用複雑化を避けたかったが、そもそも作業はローカルPCでやっているので、同期はスクリプトでシンプルに解決できることに気が付いた。 まだ開始前に検討したためincidents=0。