Ourin — SHIORI Events 3.0M (macOS) 仕様書（UKADOC互換 / ToC付き）

Status: Draft
Updated: 2025-07-28 (JST)
Target: macOS 10.15+（Catalina）〜 / Universal 2（x86_64, arm64）

目的
SSP の「[SHIORI Event リスト]」を正とし、Ourin（macOS）で語彙・挙動互換を保ちながら、OS 依存点は M‑Diff（macOS差分）として定義します。
- プロトコル：SHIORI/3.x（CRLF 改行、GET/NOTIFY の意味は原典通り）
- 文字コード：既定 UTF‑8（CP932 受理→内部 UTF‑8 正規化）
- 座標系：仮想デスクトップのグローバル座標（原点はメイン画面左上）。Cocoa 座標差は Ourin が吸収。
- パス/URL：POSIX 絶対パス or file:// を標準。相対パスは「シェル→ゴースト」順で探索。
- ValueNotify：SSP 同等のサブセットを受理（![raise/], ![notify/], ![sound], ![set,trayicon], ![set,trayballoon], ![get/set,property]）。

本書は UKADOC の語彙を尊重しつつ、各イベントの Ourin 側受理・返却・M‑Diffを一望できるようにまとめたものです。詳細の Reference 配列内容は UKADOC 原典の各節を参照してください。

0. 用語と共通仕様

• メソッド：GET（返却 Value を期待）、NOTIFY（返却 Value は無視）。
• ヘッダ：Charset/Sender/SenderType/SecurityLevel/Status/BaseID/Reference* を受理。CR+LF、末尾は空行で終端。
• ValueNotify：NOTIFY でも即時実行可能なサブセットを受理。
• SenderType：internal/external/sakuraapi/embed/raise/property/plugin/sstp/communicate。
• SecurityLevel：local/external。Ourin は external の場合、一部タグを制限。

1. M‑Diff（macOS差分）一覧

• 座標：グローバル座標（メイン画面左上）。Window/Surface 座標は Ourin が変換。
• ディスプレイ変更：NSApplication.didChangeScreenParametersNotification で捕捉し、主画面の bpp/解像度とマルチモニタ情報を生成。
• スリープ/スリープ解除/画面消灯：NSWorkspace の willSleep/didWake/screensDidSleep/screensDidWake を採用。
• スクリーンセーバ検知：DistributedNotificationCenter の com.apple.screensaver.didstart/didstop を使用。画面消灯は OnDisplayPowerStatus として分離。
• ファイル/URLドロップ：NSDraggingDestination / NSPasteboard.PasteboardType.fileURL / UTI で受理。
• ウィンドウ最小化/復元：AppKit ウィンドウ状態から合成、バルーン可視状態は Ourin が保持。
• バッテリー/電源：Energy APIs からポーリングまたは通知。

2. イベント仕様（カテゴリ別）

凡例
- ID：イベント名
- Method：既定メソッド（[NOTIFY]記載は既定 NOTIFY）
- When：Ourin が通知する契機（macOSに合わせた要約）
- Refs：Reference 概要（詳細は原典に準拠）
- Return：GET 時の返却（Value）方針
- M‑Diff：macOS固有の補足（座標/パス/API 等）

2.1 起動・終了・切り替え

…（以降の各カテゴリも同様の表を完備。全イベント名は UKADOC の分類順で列挙。）

2.2 入力ボックス

対象：OnTeachStart / OnTeach / OnTeachInputCancel / OnCommunicate / OnCommunicateInputCancel / OnUserInput / OnUserInputCancel / inputbox.autocomplete
M‑Diff：入力ウィンドウは AppKit テキスト入力。IMは NSTextInputClient。セキュリティレベル external では自動送信用タグを抑制。

2.3 ダイアログ

OnSystemDialog / OnSystemDialogCancel / OnConfigurationDialogHelp / OnGhostTermsAccept / OnGhostTermsDecline
M‑Diff：ファイル選択/カラー/ダイアログは NSOpenPanel/NSColorPanel 等の前後で通知。

2.4 時間

OnSecondChange / OnMinuteChange / OnHourTimeSignal
M‑Diff：DispatchSourceTimer で正確に駆動、AppNap 影響下はまとめ通知可。

2.5 消滅

OnVanishSelecting / OnVanishSelected / OnVanishCancel / OnVanishButtonHold / OnVanished / OnOtherGhostVanished
M‑Diff：バルーン破棄でキャンセル可能。

2.6 選択肢・アンカー

OnChoiceSelect / OnChoiceSelectEx / OnChoiceEnter / OnChoiceTimeout / OnChoiceHover / OnAnchorSelect / OnAnchorSelectEx / OnAnchorEnter / OnAnchorHover
M‑Diff：Ex は追加 Ref（修飾キー/座標等）を macOS グローバル座標で供給。

2.7 サーフェス

OnSurfaceChange / OnSurfaceRestore / OnOtherSurfaceChange
M‑Diff：描画は Core Animation/Metal/CG。座標/矩形はグローバル換算。

2.8 マウス

OnMouseClick/Ex / OnMouseDoubleClick/Ex / OnMouseMultipleClick/Ex / OnMouseUp/Ex / OnMouseDown/Ex / OnMouseMove / OnMouseWheel / OnMouseEnter(All) / OnMouseLeave(All) / OnMouseDragStart/End / OnMouseHover / OnMouseGesture
M‑Diff：ボタン/修飾キーは NSEvent 準拠。スクロールは自然方向設定を符号で正規化。

2.9 バルーン

OnBalloonBreak / OnBalloonClose / OnBalloonTimeout
M‑Diff：バルーンはウィンドウ×表示状態で管理。Break はダブルクリック等。

2.10 トレイバルーン

OnTrayBalloonClick / OnTrayBalloonTimeout
M‑Diff：通知センターにマップ。

2.11 インストール

OnInstallBegin / OnInstallComplete / OnInstallCompleteEx / OnInstallCompleteAll / OnInstallFailure / OnInstallRefuse / OnInstallReroute + 付随の「識別子/失敗理由」列挙。

2.12 ファイルドロップ

OnFileDropping / OnFileDropped / OnOtherObjectDropping / OnOtherObjectDropped / OnDirectoryDrop / OnWallpaperChange / OnFileDrop / OnFileDropEx / OnFileDrop2 / OnUpdatedataCreating/Created / OnNarCreating/Created
M‑Diff：NSDraggingDestination と NSPasteboard.PasteboardType.fileURL／UTType で受理。パスは file:// と POSIX の両方を Reference で提供。サンドボックス無効前提（開発用は Bookmark 化）。

2.13 URLドロップ

OnURLDragDropping / OnURLDropping / OnURLDropped / OnURLDropFailure / OnURLQuery / OnXUkagakaLinkOpen
M‑Diff：public.url UTI を受理。

キャラクターウィンドウへのURLドロップは、対象ゴーストに Ourin 拡張の OnURLDrop を GET で問い合わせた後、応答スクリプトが無い場合に標準の OnURLQuery を送る。 OnURLQuery の Reference は URL／スコープ番号／MIME／予定処理（nar または unknown）。 nar の場合だけ OnURLDropping → HTTPS（または明示許可時のHTTP）ダウンロード → OnURLDropped → NAR インストールの順で処理し、通信・展開・設置に失敗した場合は OnURLDropFailure を送る。Reference1 のHTTP失敗理由はステータスコード文字列、通信失敗は timeout／fileio 等の標準語彙へ正規化する。構文不正・許可外スキーム・明示許可のないHTTPは 受信開始前に拒否するため、標準の失敗イベントを発火しない。ダウンロード完了前に OnURLDropped を発火せず、未知のURLを自動ダウンロードしない。接続先は公開アドレスへ 限定し、リダイレクトも同じ検査を通す。受信には30秒の要求タイムアウト、5分のリソース タイムアウト、256 MiBのサイズ上限を設ける。

2.14 ネットワーク更新

OnUpdate / OnUpdateOther / OnUpdateCheck / OnUpdateResult / OnUpdateResultExplorer + 理由/対象種別/成功・失敗理由
M‑Diff：Ourin の更新モジュールに準拠。

2.15 時計合わせ(SNTP)

OnSNTPBegin / OnSNTPCompare(Ex) / OnSNTPCorrect(Ex) / OnSNTPFailure

2.16 メールチェック(BIFF)

OnBIFFBegin / OnBIFFComplete / OnBIFF2Complete / OnBIFFFailure

2.17 ヘッドライン/RSS

OnHeadlinesenseBegin / OnHeadlinesense.OnFind / OnHeadlinesenseComplete / OnHeadlinesenseFailure / OnRSSBegin / OnRSSComplete / OnRSSFailure + フェーズ/終了理由

2.18 カレンダー

OnSchedule5MinutesToGo / OnScheduleRead / OnSchedulesenseBegin/Complete/Failure / OnSchedulepostBegin/Complete + 種別

2.19 SSTP

OnSSTPBreak / OnSSTPBlacklisting
M‑Diff：SSTP/1.x サーバ（9801/TCP）で検出。

2.20 その他通信

OnExecuteHTTPComplete/Failure/Progress/SSLInfo / OnExecuteRSSComplete/Failure/SSLInfo / OnPingComplete/Progress / OnNSLookupComplete/Failure

2.21 送信失敗

OnRaisePluginFailure / OnNotifyPluginFailure / OnRaiseOtherFailure / OnNotifyOtherFailure

2.22 見切れ・重なり

OnOverlap / OnOtherOverlap / OnOffscreen / OnOtherOffscreen
M‑Diff：ウィンドウ位置とスクリーン境界で算出。

2.23 ネットワーク状態

OnNetworkHeavy / OnNetworkStatusChange

2.24 OS状態

OnScreenSaverStart/End / OnSessionLock/Unlock/Disconnect/Reconnect / OnCPULoadHigh/Low / OnMemoryLoadHigh/Low / OnDisplayChange/Handover/Ex / OnDisplayPowerStatus / OnBatteryNotify/Low/Critical/ChargingStart/Stop / OnDeviceArrival/Remove / OnTabletMode / OnDarkTheme / OnOSUpdateInfo / OnRecycleBin
M‑Diff*：スクリーンセーバは ScreenSaverEngine 検知＋スクリーン消灯通知で近似。ゴミ箱は macOS の「ゴミ箱」にマップ。

2.25 選択領域モード

OnSelectModeBegin/Cancel/Complete/MouseDown/MouseUp

2.26 音声認識・合成

OnSpeechSynthesisStatus / OnVoiceRecognitionStatus / OnVoiceRecognitionWord

2.27 その他

OnKeyPress / OnRecommendsiteChoice / OnTranslate / OnAITalk / OnOtherGhostTalk / OnEmbryoExist / OnNekodorifExist / OnSoundStop / OnSoundError / OnTextDrop / OnShellScaling / OnBalloonScaling / OnLanguageChange / OnResetWindowPos

2.28 Notifyイベント（capability等）

basewareversion / hwnd / uniqueid / capability / ownerghostname / otherghostname / installed / configuredbiffname / pathlist / rateofusegraph / enable_log / enable_debug / OnNotifySelfInfo / OnNotifyBalloonInfo / OnNotifyShellInfo / OnNotifyDressupInfo / OnNotifyUserInfo / OnNotifyOSInfo / OnNotifyFontInfo / OnNotifyInternationalInfo
M‑Diff：hwnd は互換ダミー（CGWindowID を 10進文字列で提供）。enable_log は Ourin の内部ロガを切り替え、log_path Resource と連携。

3. 返却規約（Value/Status/Headers）

• 200 OK（Value あり）/204 No Content（Value なし）/311/312（OnTeach 補助）/400/500（エラー）
• ValueNotify：NOTIFY 時でも即時実行できるサブセットの受理。
• SecurityLevel：external の場合は危険タグ（外部ファイル実行等）を抑止。

4. 互換性と注意

• Reference の順序・意味は UKADOC 原典に準拠。
• Ourin の Sender は Ourin。SenderType は原因に応じて付与。
• CRLF と最終空行を厳守（自動付与）。
• SJIS 受理は内部 UTF‑8 正規化（戻りは UTF‑8）。

付録A. イベント→Ourin内部APIマップ（抜粋）

• 表示/ディスプレイ：AppKit NSApplication.didChangeScreenParametersNotification と CoreGraphics のディスプレイ情報
• 表示イベントの Reference：DisplayObserver.swift が OnDisplayChange の bpp/width/height と OnDisplayChangeEx のモニタ列を生成。
• スリープ/復帰：NSWorkspace Notifications
• 電源/バッテリー：IOKit IOPowerSources の残量・残時間・充電状態・電源種別を OnBattery* へ変換。
• ドラッグ&ドロップ：NSDraggingDestination / NSPasteboard（fileURL/UTType）
• ネットワーク：Network.framework（SSTP/HTTP）
• 入力：NSEvent（修飾キー/座標）

実装状況（Implementation Status）

更新日: 2026-08-12

Ourin におけるイベントシステム実装

• [x] イベントブリッジ: EventBridge.swift にてシステムイベントの統合管理を実装済み
• [x] システムオブザーバー: 各種システムイベント監視を実装済み
• [ ] 完全なイベント網羅: 全ての SHIORI イベントの完全実装は未達成

実装済みのイベントカテゴリ

1. 時間系イベント - [x] OnSecondChange, OnMinuteChange: TimerEmitter.swift にて実装済み - [x] タイマーベースのイベント発火

2. OS 状態イベント - [x] OnSleep, OnResume: SleepObserver.swift にて実装済み - [x] OnDisplayChange: DisplayObserver.swift にて実装済み - [x] OnDisplayChangeEx: マルチモニタの実データ付きで実装済み - [x] OnDisplayPowerStatus: 画面スリープ/復帰を SleepObserver.swift から実装済み - [x] OnBatteryNotify/Low/Critical/ChargingStart/Stop: PowerObserver.swift の IOKit 実データ変換で実装済み - [x] OnSessionLock, OnSessionUnlock: SessionObserver.swift にて実装済み - [x] OnSessionDisconnect, OnSessionReconnect: NSWorkspace セッション通知で実装済み - [x] システム負荷監視: SystemLoadObserver.swift にて実装済み - [x] OnOSUpdateInfo: /usr/sbin/softwareupdate --list/--history の実履歴を起動時 NOTIFY・履歴更新時 GET で通知 - [x] OnCloseAll: 全起動ゴーストの応答再生完了を集約してからアプリを終了 - [x] 初期 Notify 系: OnNotifyUserInfo / OnNotifyOSInfo / OnNotifyFontInfo / OnNotifyInternationalInfo をmacOS実データで生成し、ユーザー名・ロケール変更時に再通知

3. ネットワークイベント - [x] OnNetworkConnect, OnNetworkDisconnect: NetworkObserver.swift にて実装済み - [x] Network.framework による監視

4. 入力系イベント - [x] マウス/キーボード監視: InputMonitor.swift にて実装済み - [x] グローバルイベント監視（NSEvent）

5. ドラッグ&ドロップ - [x] ファイルドロップ: DragDropReceiver.swift にて実装済み - [x] NSPasteboard による URL/ファイル受信

6. 外観変更 - [x] OnAppearanceChange: AppearanceObserver.swift にてダークモード切り替えを監視

7. SSTP イベント - [x] OnSendSSTP, OnNotifySSTP: SSTP サーバにて実装済み - [x] TCP/HTTP/XPC での受信

実装済みのコンポーネント

• EventBridge.swift: 全イベントオブザーバーの統合管理
• TimerEmitter.swift: 秒/分単位のタイマーイベント
• SleepObserver.swift: スリープ/復帰の監視
• DisplayObserver.swift: ディスプレイ構成変更の監視
• SessionObserver.swift: ログイン/ロック/アンロックの監視
• SystemLoadObserver.swift: CPU/メモリ負荷の監視
• NetworkObserver.swift: ネットワーク接続状態の監視
• InputMonitor.swift: グローバル入力イベントの監視
• DragDropReceiver.swift: ドラッグ&ドロップの受信
• AppearanceObserver.swift: システム外観変更の監視

未実装のイベントカテゴリ

1. 入力ボックス系 - [ ] OnUserInput, OnUserInputCancel - [ ] macOS 向け入力 UI 未実装

2. ダイアログ系 - [ ] OnChoiceSelect, OnChoiceSelectEx - [ ] 選択肢ダイアログの完全実装

3. ネットワーク更新 - [ ] OnUpdateReady, OnUpdateComplete - [ ] 自動更新機能未実装

4. ヘッドライン/RSS - [ ] OnHeadline* イベント群 - [ ] RSS フィード機能未実装

5. メール BIFF - [ ] OnBIFF* イベント群 - [ ] メールチェック機能未実装

6. 音声認識・合成 - [ ] OnSpeechInput, OnSpeechDone - [ ] macOS Speech API 統合未実装

7. カレンダー - [ ] OnCalendar* イベント群

イベント発火の流れ

システムイベント発生
  ↓
各 Observer が検出（DisplayObserver, SleepObserver など）
  ↓
EventBridge にイベント転送
  ↓
SHIORI リクエスト形式に変換
  ↓
ShioriLoader 経由で YAYA Backend へ送信
  ↓
ゴーストがレスポンスを返却

座標系とパス処理

• [x] 仮想デスクトップグローバル座標: CoreGraphics により実装済み
• [x] POSIX 絶対パス: FileManager による標準パス処理
• [x] file:// URL: URL 型による処理

自動システムイベントの有効化タイミング

概要

標準の自動システムイベント（タイマー/入力/スリープ/ディスプレイ/電源/ロケール/外観/セッション/ネットワーク/ゲームパッド/デバイス/音声認識）は、実ゴーストのロード完了を唯一の集約点として有効化されます。

実装ファイル： - Ourin/Ghost/GhostManager.swift — startEventBridgeIfNeeded(enableAutoEvents:) - Ourin/SHIORIEvents/EventBridge.swift — start(enableAutoEvents:) および内部キュー機能

有効化の流れ

GhostManager.start()
  ↓ YAYA 辞書ロード完了
  ↓ OnBoot GET 発行前
startEventBridgeIfNeeded(enableAutoEvents: !GhostManager.isRunningUnderTests)
  → EventBridge.shared.start(enableAutoEvents: true)   // テスト時は false
     → TimerEmitter / InputMonitor / SleepObserver /
        DisplayObserver / SpaceObserver / PowerObserver /
        LocaleObserver / AppearanceObserver / SessionObserver /
        NetworkObserver / GamepadObserver / DeviceObserver /
        SpeechObserver をすべて開始
     → pendingNotifies をフラッシュ（キュー済み NOTIFY を即時配送）

有効化以前の NOTIFY キュー動作

autoEventsEnabled = false の状態で broadcastNotify または broadcastNotifyCustom が呼ばれた場合、イベントは 内部キュー（pendingNotifies）に積まれます。自動イベントが有効化されると同時にキューがフラッシュされ、ゴーストへ順次配送されます。

ユニットテストでの抑制

GhostManager.isRunningUnderTests は環境変数 XCTestConfigurationFilePath または XCTestBundlePath の存在でテスト実行を検出します。テスト時は enableAutoEvents = false で EventBridge.start() を呼び出すため、タイマー・入力監視などのシステムオブザーバは起動されません。

旧動作との差分

以前のデフォルトは enableAutoEvents = false であり、名前入力ダイアログ経路（GhostManager+Display）を通過しない限り自動イベントが NOTIFY キューのみに留まる経路がありました。現在は実ゴーストロード完了が唯一の有効化ポイントとなり、ダイアログ経路の有無に関わらず自動イベントが確実に有効化されます。

変更履歴

• 2026-06-28: 自動システムイベント有効化タイミングのセクションを追加（GhostManager.startEventBridgeIfNeeded / EventBridge.start 実装に対応）
• 2025-10-20: 実装状況セクションを追加
• 2025-07-28 (JST): 初版（3.0M for macOS）。