Ui DemoSAFE

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: ui-demo
description: Playwrightを使用して美しいUIデモ動画を録画する。ユーザーがWebアプリのデモ、ウォークスルー、スクリーン録画、またはチュートリアル動画の作成を求める場合に使用する。可視カーソル、自然なリズム、プロフェッショナルな仕上がりのWebM動画を生成する。
origin: ECC
---

# UI デモ動画レコーダー

Playwrightの動画録画機能を使用して、注入されたカーソルオーバーレイ、自然なリズム、ナラティブフローを備えた美しいWebアプリのデモ動画を録画する。

## 使用場面

* ユーザーが「デモ動画」「スクリーン録画」「操作デモ」または「チュートリアル」を求める場合
* ユーザーが機能またはワークフローを視覚的に見せたい場合
* ユーザーがドキュメント、オンボーディング、ステークホルダーへのデモのために動画が必要な場合

## 3フェーズのプロセス

すべてのデモは **探索 -> リハーサル -> 録画** の3つのフェーズを経る。録画フェーズに直接ジャンプしない。

***

## フェーズ 1:探索

スクリプトを書く前に、ターゲットページを探索して実際の内容を把握する。

### なぜか

見たことのない内容のスクリプトは書けない。フィールドが `<textarea>` ではなく `<input>` の場合、ドロップダウンが `<select>` ではなくカスタムコンポーネントの場合、コメントボックスが `@mentions` や `#tags` をサポートしている場合があある。仮定は録画を静かに壊す。

### 方法

フローの各ページに移動し、インタラクティブな要素をダンプする:

```javascript
// Run this for each page in the flow BEFORE writing the demo script
const fields = await page.evaluate(() => {
  const els = [];
  document.querySelectorAll('input, select, textarea, button, [contenteditable]').forEach(el => {
    if (el.offsetParent !== null) {
      els.push({
        tag: el.tagName,
        type: el.type || '',
        name: el.name || '',
        placeholder: el.placeholder || '',
        text: el.textContent?.trim().substring(0, 40) || '',
        contentEditable: el.contentEditable === 'true',
        role: el.getAttribute('role') || '',
      });
    }
  });
  return els;
});
console.log(JSON.stringify(fields, null, 2));
```

### 確認すべき内容

* **フォームフィールド**:`<select>`、`<input>`、カスタムドロップダウン、コンボボックスのどれか?
* **選択オプション**:オプションの値とテキストをダンプする。プレースホルダーには `value="0"` または `value=""` が含まれることがあり、非空に見える。`Array.from(el.options).map(o => ({ value: o.value, text: o.text }))` を使用する。テキストに「選択」が含まれるオプションや値が `"0"` のオプションをスキップする。
* **リッチテキスト**:コメントボックスは `@mentions`、`#tags`、Markdown、絵文字をサポートしているか?プレースホルダーテキストを確認する。
* **必須フィールド**:どのフィールドがフォームの送信をブロックするか?ラベルの `required`、`*` を確認し、空のフォームを送信してバリデーションエラーを確認する。
* **動的コンテンツ**:他のフィールドを入力した後にフィールドが表示されるか?
* **ボタンラベル**:正確なテキスト(`"Submit"`、`"Submit Request"`、`"Send"` など)。
* **テーブル列ヘッダー**:テーブル駆動のモーダルには、各 `input[type="number"]` をその列ヘッダーにマッピングする。すべての数値入力が同じ意味を持つと仮定しない。

### 出力

スクリプトに正しいセレクターを書くために使用する、ページごとのフィールドマッピング。例:

```text
/purchase-requests/new:
  - 予算コード: <select>(ページの最初のドロップダウン、4オプション)
  - 希望納期: <input type="date">
  - 背景説明: <textarea>(inputではない)
  - BOMテーブル: インライン編集可能なセル、span.cursor-pointer -> inputパターン
  - 送信: <button> テキスト="送信"

/purchase-requests/N(詳細):
  - コメント: <input placeholder="メッセージを入力...">、@ユーザーと#PRタグに対応
  - 送信: <button> テキスト="送信"(入力前は無効)
```

***

## フェーズ 2:リハーサル

録画せずにすべてのステップを実行する。各セレクターが解決されることを確認する。

### なぜか

セレクターの失敗は、デモ録画が壊れる最大の原因。リハーサルは録画を無駄にする前に問題を発見する。

### 方法

`ensureVisible` を使用する——ログを記録して大きくエラーを報告するラッパー:

```javascript
async function ensureVisible(page, locator, label) {
  const el = typeof locator === 'string' ? page.locator(locator).first() : locator;
  const visible = await el.isVisible().catch(() => false);
  if (!visible) {
    const msg = `REHEARSAL FAIL: "${label}" not found - selector: ${typeof locator === 'string' ? locator : '(locator object)'}`;
    console.error(msg);
    const found = await page.evaluate(() => {
      return Array.from(document.querySelectorAll('button, input, select, textarea, a'))
        .filter(el => el.offsetParent !== null)
        .map(el => `${el.tagName}[${el.type || ''}] "${el.textContent?.trim().substring(0, 30)}"`)
        .join('\n  ');
    });
    console.error('  Visible elements:\n  ' + found);
    return false;
  }
  console.log(`REHEARSAL OK: "${label}"`);
  return true;
}
```

### リハーサルスクリプトの構造

```javascript
const steps = [
  { label: 'Login email field', selector: '#email' },
  { label: 'Login submit', selector: 'button[type="submit"]' },
  { label: 'New Request button', selector: 'button:has-text("New Request")' },
  { label: 'Budget Code select', selector: 'select' },
  { label: 'Delivery date', selector: 'input[type="date"]:visible' },
  { label: 'Description field', selector: 'textarea:visible' },
  { label: 'Add Item button', selector: 'button:has-text("Add Item")' },
  { label: 'Submit button', selector: 'button:has-text("Submit")' },
];

let allOk = true;
for (const step of steps) {
  if (!await ensureVisible(page, step.selector, step.label)) {
    allOk = false;
  }
}
if (!allOk) {
  console.error('REHEARSAL FAILED - fix selectors before recording');
  process.exit(1);
}
console.log('REHEARSAL PASSED - all selectors verified');
```

### リハーサルが失敗した場合

1. 可視要素のダンプを読む。
2. 正しいセレクターを見つける。
3. スクリプトを更新する。
4. リハーサルを再実行する。
5. すべてのセレクターが通過した後のみ続行する。

***

## フェーズ 3:録画

探索とリハーサルが通過した後にのみ、録画を作成する。

### 録画の原則

#### 1. ナラティブフロー

動画をストーリーとして計画する。ユーザーが指定した順序に従うか、このデフォルト順序を使用する:

* **エントリー**:ログインまたは開始点へのナビゲーション
* **コンテキスト**:周囲を確認して、視聴者がどこにいるか理解できるようにする
* **アクション**:主要なワークフローステップを実行する
* **バリアント**:設定、テーマ、ローカライゼーションなどの補助機能を表示する
* **結果**:結果、確認、または新しい状態を表示する

#### 2. リズム

* ログイン後:`4秒`
* ナビゲーション後:`3秒`
* ボタンクリック後:`2秒`
* 主要なステップ間:`1.5〜2秒`
* 最終アクション後:`3秒`
* 入力の遅延:文字ごとに `25〜40ms`

#### 3. カーソルオーバーレイ

マウスの動きを追うSVGの矢印カーソルを注入する:

```javascript
async function injectCursor(page) {
  await page.evaluate(() => {
    if (document.getElementById('demo-cursor')) return;
    const cursor = document.createElement('div');
    cursor.id = 'demo-cursor';
    cursor.innerHTML = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M5 3L19 12L12 13L9 20L5 3Z" fill="white" stroke="black" stroke-width="1.5" stroke-linejoin="round"/>
    </svg>`;
    cursor.style.cssText = `
      position: fixed; z-index: 999999; pointer-events: none;
      width: 24px; height: 24px;
      transition: left 0.1s, top 0.1s;
      filter: drop-shadow(1px 1px 2px rgba(0,0,0,0.3));
    `;
    cursor.style.left = '0px';
    cursor.style.top = '0px';
    document.body.appendChild(cursor);
    document.addEventListener('mousemove', (e) => {
      cursor.style.left = e.clientX + 'px';
      cursor.style.top = e.clientY + 'px';
    });
  });
}
```

オーバーレイはナビゲーション時に破棄されるため、ページナビゲーションのたびに `injectCursor(page)` を呼び出す。

#### 4. マウス

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.