# スクリーンショットと視覚検証

> データの再取得、実際の描画画像、スライドのレイアウト検査を組み合わせます。

- Human documentation: [https://docs.univer.ai/ja-JP/overview/features/shared/visual-inspection](https://docs.univer.ai/ja-JP/overview/features/shared/visual-inspection)

- Agent Markdown: [https://docs.univer.ai/ja-JP/overview/features/shared/visual-inspection.md](https://docs.univer.ai/ja-JP/overview/features/shared/visual-inspection.md)

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.3.0`

- Source: [features/shared/visual-inspection.ja-JP.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/visual-inspection.ja-JP.mdx)

---

視覚検証は内容モデルを画像とレイアウトの証拠に変換します。Agent は値と数式を確認した後、実際に描画された文字、図形、ページを確認し、Facade で修正して新しい状態を再検証できます。

## 3 種類の証拠

| 証拠 | 確認できること |
| --- | --- |
| 構造化された読み戻し | 生の値、数式と結果、段落、属性。 |
| PNG | 表示内容、切り取り、グラフ、色、構図。 |
| レイアウト診断 | 描画された幾何から規則、ID、境界、問題位置を得て修正を絞る。 |

## 内容状態と依存関係を準備する

Screenshot と Layout Lint は物化済み UnitData を受け取り、リモート target 接続や changeset 解釈はしません。共同編集では `pull()` し、数式変更の計算適用を待って `exportUnitData()` します。Worktree は該当草稿を使い、アプリは target、revision、範囲を報告に記録できます。

主 Snapshot にすべての依存は入りません。`formulaReferenceUnits` に Sheet/Relational Table の数式ソース、`embeddedUnits` に子 Unit を渡します。Render Page は依存を先に物化します。UUID 画像は `resolveUnitScreenshotImageAssets()` とアプリの resolver で解決できますが best-effort のため不足資源を確認してください。

## 内容から安定した画像へ

```mermaid
flowchart LR
A["明確な内容状態<br/>UnitData + 依存"]
B["Render Runtime<br/>ブラウザーとプロトコル"]
C["Render Page<br/>Univer の描画"]
D["準備完了を確認<br/>計算と安定した画面"]
E["PNG / レイアウト事実<br/>Agent と人のレビュー"]
A --> B --> C --> D --> E
```

`univer-render-runtime` が Node.js でアプリの Render Page を配信してブラウザーを起動し、製品プラグインが内容を復元します。双方はプロトコル版を検証します。操作は Runtime ごとの直列キューに入り、再利用後は所有者が `close()` します。

準備条件は製品ごとに異なります。数式 Shape は pending を離れるのを待ち、必要なら複数フレームの画素安定も待ちます。Relational Table はフォント、計算、活動中 table/view、DOM/Canvas の安定を確認します。pending でなくても数式エラーの場合があるため値と状態も検証します。

現在の実装は主 UnitData、数式ソース、埋め込みデータを直列化してハッシュを生成します。同じ Unit ID でも内容が変われば別セッション key となり、ID だけによる古い画像の再利用を防ぎます。

## 製品ごとの範囲

| 製品 | 範囲と出力 |
| --- | --- |
| Sheet | ワークシートと A1 範囲を指定した PNG。重要部分は明示選択する。 |
| Doc | ページの選択または列挙による個別 PNG。 |
| Slide | 1 始まりのページ番号または page ID。contact sheet も生成可能。 |
| Relational Table | 起動後の活動中テーブル／ビューを DOM + Canvas で撮影。 |
| Canvases | 内容全体、または排他的な region / elementIds。padding とレイアウト証拠に対応。 |

`unit-screenshot` は bytes、寸法、ページ／範囲識別子、推奨名を返し、アプリが保存します。Scale は 0.1–4、`maxPages` と画像単位の `maxPixels` を設定できます。倍率 2 倍は約 4 倍の画素となるため大きな内容は範囲分割します。PDF はこの 5 製品の入口に含まれません。

## スクリーンショットと Lint の共通入力

同じ Slide データと数式ソースに対して撮影と Layout Lint を行う例です。`renderRuntime` は作成済み、`slideData` は準備済みのスナップショットです。機能自体はファイルを保存しません。ページ構築と終了処理は [AI SDK 視覚検証](https://docs.univer.ai/ja-JP/ai/visual-inspection.md)を参照してください。

```ts
import { createUnitScreenshot } from '@univer-cli/unit-screenshot'
import { createUnitLayoutLint } from '@univer-cli/unit-layout-lint'

const source = {
  unitType: 'slide' as const,
  unitData: slideData,
  formulaReferenceUnits,
}
const screenshot = createUnitScreenshot({ runtime: renderRuntime })
const lint = createUnitLayoutLint({ runtime: renderRuntime })

const capture = await screenshot.capture({
  ...source,
  target: { kind: 'slide-pages', pages: [1], scale: 2 },
})
const report = await lint.lint({ ...source, pages: [1] })
```

## Slide：字形の墨跡で問題を特定する

Layout Lint はブラウザーのレイアウト事実を使います。`declared` はモデルの宣言枠、`ink` は文字の実際の墨跡を配置、整列、回転と共にページ座標へ変換した境界です。文字枠が収まっていても字形が収まるとは限りません。

| 現在の規則 | 検証内容 |
| --- | --- |
| `text-off-page` | 文字 ink がページを超える。 |
| `text-escapes-container` | 文字が対応する小さな不透明コンテナーを明確に超える。 |
| `text-overlaps-text` | 2 つの文字 ink が大きく重なる。 |

`coverage.pages` と `coverage.rules` が検証範囲を示します。Finding は `pageId`、要素 `id`、`text.ink` と該当する `overflow`、`container`、`other` を持ち、安定した `fingerprint` で修正前後を比較できます。現在はすべて warning で、画像と併せて確認します。空リストは選択範囲で規則が発火しなかったことだけを示します。

## Canvases：描画済みコネクター経路を確認する

Canvases 撮影は `layoutAnalysis` としてブラウザーで解決した routes、issues、summary を返します。Slide 限定の `unit-layout-lint` とは別です。モデルで自動経路が未解決なら、`source: 'rendered'` で最終経路を確認します。

要素を横切る線、交差、矢印やラベルの衝突に対し、`connectorIds`、`elementIds`、`focusBounds` が返ります。対象を修正して region または elementIds で局所撮影し、全体も再確認できます。視覚的な問題を具体的な Facade 編集へ結び付けます。

## 証拠を引き渡す

```mermaid
flowchart LR
A["Facade 編集"]
B["値と数式を読み戻す"]
C["画像 + 診断"]
D["ID に基づき修正"]
E["新しい状態を再確認"]
F["人のレビュー / 引き渡し"]
A --> B --> C --> D --> E --> F
D --> B
```

構造化結果、範囲・ページ情報、画像、診断を一緒に保存します。画像は数式の正しさを証明せず、Lint は目視確認を置き換えません。ツールバー、フォーカス、ポップアップは Web エディターで確認し、Unit 間依存の読み込みも検証します。

[Worktree](https://docs.univer.ai/ja-JP/overview/features/shared/worktree.md) を Ready にする前に検証し、内容差分と証拠を対応させます。実行は[ヘッドレスとサーバー計算](https://docs.univer.ai/ja-JP/overview/features/shared/server-calculation.md)、編成は [Agent と自動化](https://docs.univer.ai/ja-JP/overview/features/shared/agents.md)を参照してください。

[機能一覧に戻る](https://docs.univer.ai/ja-JP/overview/features.md)