SHIORI Events — 3.0M / 2.0M 互換（macOS） 仕様書

Status: Draft / macOS 10.15+ / Universal 2（arm64・x86_64）
Updated: 2025-07-27 (JST)
互換方針: UKADOC の SHIORI イベント語彙（3.0/3.1拡張）を踏襲し、OS 依存の値・通知だけを macOS ネイティブ API へ置換。
文字コード: 入出力とも UTF‑8 を標準。互換のため CP932（SJIS）受理 → 内部で UTF‑8 正規化。
改行: LF 推奨（CRLF 受理）。

1. 目的と範囲

• 本仕様は、Ourin（ベースウェア, macOS）で SHIORI イベントを発火・配送するための対応表と動作要件を定義する。
• SSP/UKADOC のイベント名・意味は語彙互換で維持し、Windows 固有値は macOS の等価データへ置換または省略（未定義）。

2. 基本ポリシー（互換/座標/UTType/時刻）

• 互換：既存イベント名・解釈は UKADOC に従う。
• 座標系：イベントで渡すスクリーン座標は AppKit 既定＝左下原点（pt）。必要に応じて トップ左基準の補助値（TopLeftX/Y）を M‑Add で併送可。
• UTType：ドラッグ＆ドロップやクリップボードは NSPasteboard/UTType を基準とする（public.plain-text/public.url/public.file-url 等）。
• 時刻：ローカル時刻を返却。ミリ秒は Date + mach_absolute_time などで補完可。

3. イベント分類

• ライフサイクル（起動/終了/切替）
• 入力（キーボード/マウス/ホイール）
• ドラッグ＆ドロップ（テキスト/URL/ファイル）
• 表示/ウィンドウ/デスクトップ（画面変更/Spaces/スケール）
• 電源/バッテリー/サーマル
• ロケール/外観（テーマ）/言語
• Web/URL（x‑ukagaka‑link 等）

4. イベント別マッピング表（抜粋）

4.1 ライフサイクル

4.2 入力（キーボード/マウス）

4.3 ドラッグ＆ドロップ

4.4 表示/ウィンドウ/デスクトップ

4.5 電源/バッテリー/サーマル

4.6 ロケール/外観/言語

4.7 Web/URL 連携

5. 追加定義（M‑Add）

• OnSpaceChanged：NSWorkspace.activeSpaceDidChangeNotification により Spaces 切替を通知。
• OnAppearanceChanged：ダーク/ライト切替を通知。Appearance=light|dark|highcontrast 等のパラメータを返す。
• OnThermalStateChanged：State=nominal|fair|serious|critical。

6. パラメータ規定

• 座標：screenX,screenY は 左下原点の pt。補助として topLeftX,topLeftY を併送可。
• 修飾キー：Command|Option|Shift|Control|CapsLock|Function などのビット名。
• UTType：public.plain-text/public.url/public.file-url を基本。拡張は UTType 階層の同等性で判定。
• Encoding：返却は UTF‑8 固定。

7. サンドボックス/セキュリティ

• ファイル D&D：App Sandbox 環境では security‑scoped URL を開始/終了で管理。
• 外部由来イベント（SSTP/URL スキーム）からのパス入力は制限パスにサニタイズ。

8. 互換性の注意と非対応

• Windows 固有の語彙（HWND 等）は未定義。
• スクリーンセーバ Start/End は macOS 公開 API が無いため、ディスプレイスリープ/復帰で近似（任意有効化）。

9. 仕様例（リクエスト/レスポンス）

## OnURLDrop の例（単一）
GET SHIORI/3.0
ID: OnURLDrop
Sender: Ourin
Reference0: https://example.org/
SecurityLevel: external

###

SHIORI/3.0 200 OK
Value: \0\s[0]URLを受け取りました：%reference[0]\e

付録A: 代表 API 対応表

• Spaces 変更 → NSWorkspace.activeSpaceDidChangeNotification
• 画面構成変更 → NSApplication.didChangeScreenParametersNotification / CGDisplay Reconfig
• キー/修飾 → NSEvent.keyCode / NSEvent.ModifierFlags
• D&D 種別 → NSPasteboard.PasteboardType.url / public.plain-text / public.file-url
• Power/Battery → IOKit Power Sources（通知＋照会）
• 外観 → NSApplication.effectiveAppearance

付録B: テスト観点チェックリスト

• [ ] URL/ファイル/テキスト D&D の判定と文字コード
• [ ] 複数ディスプレイ/スケール変更の座標・DPI 追随
• [ ] Sleep/Wake・AC/バッテリー切替・サーマル状態
• [ ] ロケール変更・テーマ切替
• [ ] セキュリティ（Sandbox の security‑scoped URL、外部入力の検証）

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

動作概要

タイマー（OnSecondChange/OnMinuteChange/OnHourTimeSignal）・入力/マウス・スリープ/復帰・ディスプレイ変更・電源状態・ロケール・外観（テーマ）・セッション・ネットワーク・ゲームパッド・デバイス・音声認識の各自動システムイベントは、実ゴーストのロード完了時点を唯一の集約点として EventBridge 内で有効化されます。

実装ファイル： - Ourin/Ghost/GhostManager.swift — startEventBridgeIfNeeded(enableAutoEvents:) および isRunningUnderTests - Ourin/SHIORIEvents/EventBridge.swift — start(enableAutoEvents:) / broadcastNotify / flushPendingNotifies

有効化以前の NOTIFY キュー

autoEventsEnabled = false の状態では、broadcastNotify / broadcastNotifyCustom に渡されたイベントは内部キュー (pendingNotifies) に積まれ、即時配送されません。有効化されると同時にキューがフラッシュされ、順次ゴーストへ配送されます。

テスト時の抑制

GhostManager.isRunningUnderTests が true（環境変数 XCTestConfigurationFilePath または XCTestBundlePath の存在で判定）の場合、EventBridge.start(enableAutoEvents: false) が呼ばれ、タイマーや入力監視を含むシステムオブザーバは起動されません。