# Sceneの操作

Canonical: https://docs.shumoku.dev/en/editor/scene
Language: en

apps/editor/docs/pages/scene.md

# Sceneの操作

平面図の登録、縮尺設定、機器配置と配線の微調整。

This document is currently available in Japanese only.

Scene は、平面図上に機器・端子を配置して物理的な配線経路を編集する画面。 論理的な接続構造を扱う [Diagram](https://docs.shumoku.dev/en/editor/diagram) とは役割を分ける。 この文書は現在の操作と、座標・表示・操作判定の設計方針を扱う。 保存ファイルは [project-file.md](https://github.com/konoe-akitoshi/shumoku/blob/4373ce0092ba4581da2365007eb95ca144ac6900/apps/editor/docs/design/project-file.md)、アイコンの優先順位は [icon-model.md](https://github.com/konoe-akitoshi/shumoku/blob/4373ce0092ba4581da2365007eb95ca144ac6900/apps/editor/docs/design/icon-model.md) を参照。

## 図面の準備

*   Hierarchy で対象を選んで **Scene** に切り替える。論理サブグラフでは Scene は利用できない。
*   右側ツールバーの **Upload background image** から平面図の画像を登録する。 登録後は **Replace background image** で差し替え、**Remove background** で背景を外せる。
*   **Calibrate scale** を押し、図面上で実距離が分かる二点をクリックする。 表示された入力欄に正の距離をメートルで入力して確定する。途中の Esc で取り消せる。 再設定は **Re-calibrate** を使う。
*   **Place item** から Empty node、Wall outlet、EPS / riser、Patch panel、または登録済み製品を選び、 キャンバスをクリックして配置する。配置待ちの Esc で取り消せる。
*   ツールバーの **Rename** は Scene 自体の名前を変更する。機器の名前変更とは別の操作。

背景画像だけを登録しても実距離は決まらない。配線長を使う場合は縮尺を設定する。

## 操作

編集操作は Edit モードで行う。View モードでは機器の移動・リサイズ・名前変更・配線経路編集を行わない。

| 対象 | 操作 | 結果 |
| --- | --- | --- |
| 表示範囲 | 左下の拡大・縮小・全体表示ボタン | 表示倍率・範囲を変更する。保存座標は変わらない |
| 表示範囲 | スクロール、またはマウス中ボタンでドラッグ | 図面をパンする |
| 機器・端子 | 本体をドラッグ | 配置を移動する |
| 機器のサイズ | 選択 → ツールバーの「Resize node」→ ハンドルをドラッグ | 縦横比を維持して表示サイズを変更する |
| 名前 | ラベルをダブルクリック、または選択時の「Rename」 | 名前の入力を開始する |
| 名前 | ラベルにフォーカスして Enter / Space / F2 | 名前の入力を開始する |
| 名前の入力中 | Enter / フォーカスを外す | 変更を確定する。IME 変換確定の Enter は編集確定に使わない |
| 名前の入力中 | Esc | 入力を取り消す |
| 配線 | クリック | 配線区間を選択する |
| 選択済み配線の線分 | 線本体をドラッグ | 線分を垂直方向に平行移動する。斜めの線分も傾きを維持する |
| 選択済み配線の角付近 | 線本体からドラッグ | 近くの既存の折れ点を移動する |
| 選択済み配線 | Alt（Mac は Option）を押しながら線本体をドラッグ | 折れ点を追加して移動する |
| 線本体からのドラッグ中 | Esc | 操作開始前の配線に戻す |

線本体のドラッグは、先に配線をクリックして選択してから行う。 機器や端子に接する線分を平行移動するときは、必要な折れ点を追加し、機器・端子の位置を維持する。 通常時の折れ点マーカーは非表示で、ホバーまたはマーカーの選択時に表示する。 配線の距離表示は平面図の縮尺設定がある場合に表示され、選択中も維持する。 ケーブル種別の色の凡例は、配線を選択しても隠さない。

## 座標・ズームの設計

保存する図面座標と、画面上の操作しやすさを分ける。

*   **図面座標**：配置と `Link.bends` は図面座標で保持する。ズームしても保存座標を書き換えない。
*   **表示**：アイコン、通常のラベル、配線の太さは図面と一緒に拡大縮小する。線幅は図面単位で `2 × wireScale`。
*   **操作判定**：線を拾う透明な領域は画面上で最低 12 px の幅を確保する。既存の折れ点を優先する距離は画面上で 8 px。
*   **入力 UI**：名前の入力欄と機器の選択枠は逆ズーム倍率で補正する。通常のラベルはこの補正の対象にしない。
*   **ドラッグ**：開始時の座標にポインターの移動差分を足す。掴んだ瞬間に折れ点をポインター位置へ飛ばさず、小数座標を保持する。

`screenToFlowPosition` で画面座標を図面座標に変換し、操作判定の距離には逆ズーム倍率を使う。 倍率変更に伴う再描画でも選択状態を保持する。

## 配線編集と Undo

線本体からのドラッグは、画面上で 3 px 以上動き、実際に経路が変化した時点でトランザクションを開始する。 ドラッグ中の更新はまとめ、確定した操作一回を Undo 一回にする。 クリックだけ、線分に沿った移動だけ、開始位置に戻った操作では不要な履歴や折れ点を残さない。

Esc、ポインター操作の取消、ウィンドウのフォーカス喪失、対象コンポーネントの破棄では、 元の折れ点を復元してトランザクションを閉じる。 これは `wire-edit.ts` が扱う**線本体からのドラッグ**の仕様であり、 Svelte Flow の機器・端子・折れ点マーカーそのもののドラッグに同じ取消動作を保証するものではない。

折れ点の挿入先は `afterIndex` と既存の折れ点の順序から決める。 途中に端子がある配線でも、別区間の折れ点を誤って選択・並べ替えしない。

## 実装と検証

| ファイル（`apps/editor/src/lib/` 配下） | 責務 |
| --- | --- |
| `components/scene/SceneCanvas.svelte` | 図面データと Svelte Flow の橋渡し、選択保持、表示範囲 |
| `components/scene/SceneNodeIcon.svelte` | 指定アイコン優先の描画と画像読み込み失敗時の代替表示 |
| `components/scene/SceneNodeLabel.svelte` | ラベル、名前入力、IME・フォーカス処理 |
| `components/scene/SceneEdge.svelte` | 線・距離表示、ヒット領域、線本体のドラッグ開始 |
| `scene/node-geometry.ts` | 図面上のサイズと操作用の倍率補正 |
| `scene/wire-drag.ts` | 操作対象の判定、折れ点の挿入、開始位置からの移動計算 |
| `components/scene/wire-edit.ts` | ポインター処理、取消、Undo のトランザクション |

リポジトリルートから `bun run --cwd apps/editor test` と `bun run --cwd apps/editor typecheck` を実行する。 `node-geometry.test.ts`、`wire-drag.test.ts`、`wire-edit.test.ts` が 倍率補正・移動計算・区間内の順序・取消・Undo を検証する。

実画面では、縮小・拡大した図面での選択と微調整、長いラベル、指定アイコン、 機器・折れ点マーカーとのヒット領域の重なりを別途確認する必要がある。 機器・折れ点マーカー自体の最小ヒット領域、ラベルの衝突回避、数値による座標入力、 グリッドや他の機器へのスナップは、今回の精密操作の修正では追加していない。