# Muse スペース実行環境リファレンス（Muse 向け）

| 項目 | 内容 |
|---|---|
| 文書の目的 | Muse の「スペース」（Web アーティファクト）を作成・編集・診断する Muse が、スペース特有の実行環境仕様によって通常の Web 開発の前提が崩れる箇所を事前に把握し、同じ失敗を繰り返さないための技術リファレンス |
| 観測期間 | 2026-11-08〜2026-11-09（JST） |
| 観測環境 | Muse（Web 版および Android アプリ）における静的（static）スペース。フルスタック（fullstack）については §2 の一般事項のみ未検証事項として区別する |
| 証拠レベルの表記 | 本文中では、各記述の根拠を次の4区分で示す。「実測」＝実際のスペース上で再現・確認した事実。「検査記録」＝スペースの診断・監査プロセスの出力で確認した事実。「製品文書」＝Muse の公式ドキュメント（`~/docs/`）に基づく記述。「推測」＝未検証の推論であり、そのまま前提にしてはならない |

---

## 1. 最重要事項（要約）

スペースの配信ランタイムは、ページ内の `innerHTML` への書き込みを横取りし、`<template>` 要素を経由した再パース（サニタイズ処理）を行ってから DOM に差し込む。このため、**JavaScript から HTML 文字列として流し込んだ SVG 要素（`<path>` 等）は SVG 名前空間を失い、画面に描画されない**。

対処は単純であり、動的に生成する SVG 要素は文字列ではなく `document.createElementNS('http://www.w3.org/2000/svg',...)` で生成し、`setAttribute` で組み立てること。詳細は §4 を参照のこと。

加えて、検証方法にも落とし穴がある。**書き出した単一 HTML ファイルで動作しても、スペースとして配信された状態で動作するとは限らない**（逆も同様）。最終確認は必ずスペースとして表示された状態で行うこと（§6）。

---

## 2. スペースの基本構造（根拠：製品文書）

- スペースは Web アーティファクトの呼称である。ユーザーの Library またはサイドバーに配置される。
- 種別は2つある。
- **static**：内容はビルド時に固定され、訪問者の入力は保存されない。クライアント側 JavaScript、地図、CSS フレームワーク等は利用可能。公開リンクでの共有（publish）が可能なのはこの種別のみであり、公開の都度、ユーザーの承認が必要である。
- **fullstack**：保存・サーバー処理を持つアプリ。公開リンクは作れない。
- 静的スペースは単一の自己完結 HTML ファイルとして書き出し（export）が可能である。書き出しではアセットがインライン化される。ただし §6 のとおり、書き出しファイルの動作は配信時の動作を保証しない。
- データやファイルはユーザーの Muse 環境内に保持され、公開されるのは静的スナップショットのみである。

## 3. ソースとビルド成果物の配置

スペースの実体はワークスペース内に次のような構成で存在する（slug はスペース識別子）。

```
~/workspace/ts-spaces/<slug>/
├── index.html # ソース（エントリポイント）
├── assets/ # 画像等の静的アセット
├── space.json # スペースのメタ情報
├── audits/ # ビルド監査（スクリーンショット等）の履歴
├──.space-build/ # ビルド成果物（manifest.json を含む）
└──.space-build-cvm/ # 配信ランタイム向けビルド成果物
```

重要なのは、**ソース（index.html）と配信物（.space-build-cvm 側）が同一ではない**という点である。配信時にはランタイム側のラッパーが介在する。問題の切り分けでは「どの成果物が、どの環境で動いているか」を常に意識すること。

## 4. 配信ランタイムによる DOM 書き込みの横取り（根拠：検査記録・実測）

### 4.1 仕組み

配信ランタイム（`.space-build-cvm` 側のビルドに含まれる）には、ページ内の `innerHTML` 設定を横取りする仕組み（内部的には `__tunnel.setInnerHTML` と呼ばれる処理）が存在する。書き込まれた HTML は `parseAndCleanHtml` という処理を通り、`document.createElement('template')` に `innerHTML` を設定して再パース（クリーン処理）されてから実際の DOM に差し込まれる。

### 4.2 帰結：文字列で流し込んだ SVG が描画されない

`<template>` 内で再パースされた裸の `<path>` 等の SVG 部品は、外来コンテンツ（foreign content）として扱われず、HTML 名前空間の未知要素となる。その要素は DOM 上に存在しても SVG としては描画されない。

実際に観測された事例（§7 のケーススタディ）では、SVG レイヤーに対して `svg.innerHTML = '<path.../>'` の形で接続線を描画するコードが、**素の HTML ファイルでは正常に描画され、スペース配信では一切描画されなかった**。

### 4.3 無事だったものとの対比

同じページ内で、最初から HTML ソースに `<svg>` ルート要素ごと静的に書かれていたアイコン（ハートマーク）は正常に表示されていた。これは、文書パースの段階では `<svg>` ルートが外来コンテンツとして正しく認識されるためであり、この対比が原因特定の決め手となった。

すなわち、問題は「SVG そのもの」ではなく「**実行時に文字列として流し込む経路**」にある。

### 4.4 対処法（確認済み）

動的に生成する SVG 要素は、文字列を使わず DOM API で生成すること。

```js
const SVGNS = 'http://www.w3.org/2000/svg';
const path = document.createElementNS(SVGNS, 'path');
path.setAttribute('d', 'M 0 0 L 100 100');
path.setAttribute('stroke', '#c0392b');
svg.appendChild(path);
```

- 要素の除去は `removeChild` 等の DOM 操作で行う（`innerHTML = ''` での一括消去も横取り対象になり得るため、実績のある方式に寄せること）。
- `setAttribute` は、URL 系属性を除き素通しであることがランタイム側で確認されている。URL 系属性はサニタイズ対象になり得るため、動的に URL を設定する場合は配信環境で個別に確認すること。

### 4.5 他の動的マークアップへの波及（要注意）

`parseAndCleanHtml` は名称のとおりクリーン処理（サニタイズ）を含むとみられる。したがって次
の要素も、文字列流し込みでは配信環境で欠落・無効化される可能性がある。ただし本節の項目は、SVG 以外については推測の域を出ないため、個別の確認なしに断定してはならない。

- MathML 等の他の外来コンテンツ（SVG と同じ理由で名前空間を失う可能性が高い）
- イベントハンドラ属性（`onclick="..."` 等）や `javascript:` URL 等、サニタイザが除去しがちな属性
- `<script>` や `<style>` の実行時注入
- `srcdoc` 属性を持つ iframe の内容

動的コンテンツは原則として `createElement` / `createElementNS` と `addEventListener` で組み立てるのが、配信環境でも素の環境でも動く堅牢な方式である。

## 5. スペース特有ではないもの（誤認防止）

切り分けの際に「スペース特有の仕様」と誤認しやすいが、実際には通常の Web の挙動であるものも多い。観測事例からは次が挙げられる。

- CSS の重なり順（z-index）と不透明な背景による遮蔽は、通常の CSS の問題であり、プラットフォーム側の仕様ではない。
- メディアクエリや `window.innerWidth` による分岐は、スペースが表示されているパネル／画面の実効幅で評価される。ユーザーのモニター解像度と、スペースの表示幅は一致しないことがある。
- 画像読み込み完了やフォント読み込みの前後でレイアウトが確定し、実測位置（`getBoundingClientRect`）が変わることも通常の挙動である。位置依存の描画は、読み込み完了時とリサイズ時（ResizeObserver 等）にも再実行する設計が有効であった。

問題に遭遇した際は、まず通常の原因（CSS、タイミング、幅の分岐）を疑い、それらを除外した後に配信ランタイム側の仕様を疑う順序が効率的である。

## 6. 検証方法論（最重要の実務知見）

### 6.1 書き出しファイルは配信環境の代理にならない

静的スペースの書き出し（単一 HTML）は、配信ランタイムを経由しない。したがって、

- 書き出しで見える ≠ スペースで見える
- 書き出しで壊れる ≠ スペースでも壊れる

の双方が成り立つ。書き出しは「コード自体の正しさ」の確認には使えるが、「配信環境での動作」の証明にはならない。

### 6.2 ビルド監査のスクリーンショットも万能ではない

ビルド時の監査キャプチャは特定の幅（観測例ではデスクトップ 1440px、モバイル 390px）で撮影される。ユーザーの実表示幅や実表示経路（チャット内のプレビュー、サイドバー、モバイルアプリ）とは条件が異なるため、監査で「見えている」ことがユーザーの画面で見えることを保証しない。観測事例では、監査で正常とされた表示が、ユーザーの実環境では再現しなかった。

### 6.3 差分実験の設計

原因が「コードか、幅か、配信環境か」で割れる場合は、ユーザーと協力して次の4象限を埋める実験が決定的に有効であった。

| | 狭幅レイアウト | 広幅レイアウト |
|---|---|---|
| **スペースとして表示** | × 見えない | × 見えない |
| **書き出し HTML として表示** | ○ 見える | ○ 見える |

この結果から「幅」でも「コード」でもなく「配信環境」が要因であることが一意に絞り込めた。症状が環境依存らしく見えたら、推測で修正を重ねる前に、この形の切り分けを先に行うことを強く推奨する。

### 6.4 検証の原則

1. 最終確認は、ユーザーが実際に見る経路（スペースとして表示した状態）で行う。
2. 「コード上で正しい」と「表示されている」は別の主張であり、混同しない。過去の観測事例では、コード確認のみを根拠に「直った」と報告し、実際には直っていなかったことが複数回あった。
3. ユーザーの実機報告は、監査結果よりも優先されるべき一次情報である。矛盾する場合は監査の条件（幅・経路・パース経路）を疑う。

## 7. ケーススタディ：接続線がスペースでのみ描画されなかった事例

### 7.1 症状

静的スペース上のマップ UI で、カードとピンを結ぶ SVG の接続線（12本）が、ユーザーの環境では全く表示されなかった。

### 7.2 経緯（失敗の連鎖を含む）

1. **第一幕**：接続線レイヤーの z-index が低く、不透明なステージ背景に隠れていた（通常の CSS の問題）。レイヤー順と経路（迂回型の折れ線）を修正。
2. **第二幕**：依然として見えない。原因として、幅 1100px 以下で接続線を無効化する分岐（JS と CSS の双方）が残存していたことを特定し撤廃。狭幅専用の描画も追加。
3. **第三幕**：それでもユーザーの環境でのみ見えない。ユーザーが §6.3 の4象限実験を行い、「書き出しでは見える／スペースでは見えない」ことが確定。
4. **解決**：配信ビルドを精査し、§4 の `innerHTML` 横取りと `<template>` 再パースが原因であることを特定。描画を `createElementNS` 方式に書き換え、スペース上でも接続線が表示されることを確認して解決。

### 7.3 教訓

- 「見えない」という症状は、複数の独立した原因が重なっていた。各修正はそれぞれ正しかったが、最後の1つが残っている間は症状が変わらず、「直っていない」という結果だけが見える。
- 環境差分の切り分け（§6.3）を早期に行っていれば、第一幕・第二幕の修正を「配信環境では無意味な変更」と誤認せずに済んだ可能性がある一方、第三幕の原因にはより早く到達できたはずである。
- 動的 SVG を文字列で生成する書き方は、通常のブラウザでは何の問題もなく動くため、コードレビューだけでは危険性を検出しにくい。スペース向けのコードでは最初から DOM API で組み立てるべきである。

## 8. 実装チェックリスト

スペース向けに動的コンテンツを実装する際の確認項目である。

- [ ] 動的 SVG（path、circle、line 等）は `createElementNS` で生成しているか。`innerHTML` への文字列代入で SVG を作っていないか。
- [ ] 動的要素の除去は DOM 操作（removeChild 等）で行っているか。
- [ ] イベントは `addEventListener` で登録しているか（属性への文字列登録に依存していないか）。
- [ ] URL 系属性を動的に設定する場合、配信環境で実際に解決されることを確認したか。
- [ ] 幅による分岐（メディアクエリ、`innerWidth`）が、ユーザーの実表示幅でも意図通りか。
- [ ] 位置依存の描画は、画像・フォント読み込み後とリサイズ時にも再実行されるか。
- [ ] 最終確認を、書き出しではなくスペースとして表示した状態で行ったか。
- [ ] ユーザーの実機報告と検証結果が矛盾した場合、検証側の条件を疑ったか。

## 9. 未確認事項・免責

- 本書の観測は静的スペースにおける単一事例を中心とする。フルスタックのスペース、接続（コネクタ）を利用するスペース、共有（publish）された状態でのランタイム挙動は、本書の観測範囲外である。
- §4.5 の項目は推測であり、未検証である。各項目は実地に確認してから前提とすること。
- ランタイムの内部名称（`__tunnel`、`parseAndCleanHtml` 等）は観測時点の実装に基づくものであり、公式に公開された API ではない。アップデートにより変更・撤廃される可能性がある。
- **本書の内容を鵜呑みにしないこと。** 仕様はアップデートで変わり得るし、本書自体にも誤りが含まれ得る。自分の担当するスペースで、自分の目で確かめることが常に優先する。本書は「確かめるべき候補のリスト」として使うのが正しい用途である。

---

*本書は 2026-11-08〜2026-11-09 に観測された Muse スペースの挙動に基づく非公式の技術メモであり、Muse／Meta の公式文書ではない。*