Ourin Onboarding Guide

1. プロジェクト概要

• Ourin (桜鈴) は、macOS ネイティブの ukagaka ベースウェアであり、SHIORI や SSTP などの既存規格と互換性を持つデスクトップキャラクター基盤です。（ソース参照: CLAUDE.md）
• リポジトリには Xcode プロジェクトと Swift/C++ で実装された多数のサブシステムが含まれ、既存の ukagaka エコシステムと連携します。（ソース参照: CLAUDE.md）

2. リポジトリ構成の俯瞰

• Ourin/: macOS アプリ本体。SwiftUI ベースの UI と、FMO・SHIORI・プラグインなど主要機能モジュールを含みます。（ソース参照: CLAUDE.md）
• OurinTests/: Swift 製ユニットテスト群。xcodebuild の test ターゲットで実行されます。（ソース参照: CLAUDE.md）
• docs/: SHIORI/SSTP/PLUGIN 仕様や実装ガイドを収録したドキュメント集。新機能の設計時には参照が推奨されます。（ソース参照: CLAUDE.md）
• Samples/: リファレンス実装・モックアップ等の補助資料。探索してベストプラクティスを把握してください。（ソース参照: CLAUDE.md）
• yaya_core/: YAYA 互換の C++ ランタイム。Swift プラグインとの連携は docs/connect_swift.md を参照します。（ソース参照: docs/connect_swift.md）

3. アプリ起動時に動作する主要サブシステム

OurinApp.swift の AppDelegate.applicationDidFinishLaunching では、下記のようにサブシステム初期化が段階的に進みます。（ソース参照: Ourin/OurinApp.swift）

1. FMO 初期化: FmoManager を生成し、既に別プロセスが動作していないか確認します。（ソース参照: Ourin/OurinApp.swift）
2. Web ハンドラ登録: x-ukagaka-link スキームを Swift 側で処理できるようにします。（ソース参照: Ourin/OurinApp.swift）
3. プラグイン検出: PluginRegistry が .plugin / .bundle を探索・ロードし、メタ情報を解析します。（ソース参照: Ourin/OurinApp.swift）（ソース参照: Ourin/PluginHost/PluginRegistry.swift）
4. HEADLINE モジュール読込: ニュースティッカー等の Headline API プラグインを登録します。（ソース参照: Ourin/OurinApp.swift）
5. SHIORI イベントブリッジ起動: EventBridge がシステムイベントを SHIORI/SSTP へ転送します。（ソース参照: Ourin/OurinApp.swift）
6. 外部 SSTP サーバ: OurinExternalServer が TCP/HTTP/XPC の受け口を開き、外部クライアントとの通信を受け付けます。（ソース参照: Ourin/OurinApp.swift）（ソース参照: CLAUDE.md）
7. プラグインイベントディスパッチャ: ロード済みプラグインへイベント配送を開始します。（ソース参照: Ourin/OurinApp.swift）
8. ゴースト選択と起動: ユーザー設定または同梱の emily4.nar を NarInstaller で展開し、GhostManager がゴーストの UI を描画します。（ソース参照: Ourin/OurinApp.swift）（ソース参照: Ourin/Ghost/GhostManager.swift）

4. サブシステム別の理解ポイント

• FMO (Forged Memory Object): POSIX 共有メモリと名前付きセマフォで 64KB の共有領域を提供し、単一インスタンス制御や他プロセスとの通信に利用します。FmoManager が FmoMutex / FmoSharedMemory を統合します。（ソース参照: docs/About_FMO.md）
• ゴースト実行環境: GhostManager が YAYA 辞書の読み込み、SakuraScript 実行、ウィンドウ描画を担当します。Surface/Scope 切り替えやバルーン文字列更新もここで行われます。（ソース参照: Ourin/Ghost/GhostManager.swift）
• NAR パッケージ管理: NarRegistry と NarInstaller が ghost/・balloon/ 等のディレクトリを走査し、ユーザーが導入したパッケージを列挙・展開します。（ソース参照: Ourin/Nar/NarRegistry.swift）（ソース参照: Ourin/OurinApp.swift）
• プラグイン連携: PluginRegistry が descript.txt のメタデータを Shift_JIS/UTF-8 を自動判別しつつ解析し、ロード済みプラグインへイベントを送出します。Swift でプラグインを実装する場合は C ABI でのエクスポートやメモリ管理指針に留意してください。（ソース参照: Ourin/PluginHost/PluginRegistry.swift）（ソース参照: docs/connect_swift.md）
• 外部通信: OurinExternalServer 以下のサーバ群が SSTP や XPC を通じて他アプリ・外部ゴーストと連携します。イベントブリッジやプラグインディスパッチャと組み合わせて、Ourin 外部との相互運用を実現します。（ソース参照: CLAUDE.md）

5. ビルド・テスト・デバッグ

• 開発は Xcode (macOS) を前提とし、xcodebuild -project Ourin.xcodeproj -scheme Ourin build でビルド、xcodebuild -project Ourin.xcodeproj -scheme Ourin test でテストを実行します。（ソース参照: CLAUDE.md）
• ローカル起動は Xcode から実行するか、xcodebuild ... build && open build/Release/Ourin.app のワンライナーを使用します。（ソース参照: CLAUDE.md）
• プラグイン連携の検証では、docs/connect_swift.md のテスト戦略（単体・結合・ロングラン）を参考にしてください。（ソース参照: docs/connect_swift.md）

6. 次に取り組むと良い学習ステップ

1. 仕様ドキュメントの熟読: docs/ 配下の SHIORI/SSTP/PLUGIN 仕様を読み、Ourin 固有拡張との違いを把握する。（ソース参照: CLAUDE.md）
2. GhostManager の追跡: GhostManager のフローを追い、YAYA 辞書読込から SakuraScript 表示までの処理を Xcode のブレークポイントで確認する。（ソース参照: Ourin/Ghost/GhostManager.swift）
3. プラグイン試作: docs/connect_swift.md を基に最小限の Swift プラグインを作成し、PluginRegistry によるロード挙動を観察する。（ソース参照: Ourin/PluginHost/PluginRegistry.swift）（ソース参照: docs/connect_swift.md）
4. FMO デバッグ: 共有メモリの初期化・解放シーケンスを FmoManager のコードと docs/About_FMO.md で復習し、マルチインスタンス検出ロジックを理解する。（ソース参照: Ourin/OurinApp.swift）（ソース参照: docs/About_FMO.md）

このガイドを出発点に、各モジュールの実装と周辺ドキュメントを行き来しながら理解を深めてください。新しい機能追加時は、既存のサブシステムとの連携や規格準拠を最優先で検討することを推奨します。