Merge pull request #25 from CoderGamester/develop

Release 1.1.0

Author: CoderGamester

AGENTS.md

@@ -0,0 +1,154 @@
+# GameLovers.UiService - AI Agent Guide
+
+## 1. Package Overview
+- **Package**: `com.gamelovers.uiservice`
+- **Unity**: 6000.0+
+- **Dependencies** (see `package.json`)
+  - `com.unity.addressables` (2.6.0)
+  - `com.cysharp.unitask` (2.5.10)
+
+This package provides a centralized UI management service that coordinates presenter **load/open/close/unload**, supports **layering**, **UI sets**, and **multi-instance** presenters, and integrates with **Addressables** + **UniTask**.
+
+For user-facing docs, treat `docs/README.md` (and linked pages) as the primary documentation set. This file is for contributors/agents working on the package itself.
+
+## 2. Runtime Architecture (high level)
+- **Service core**: `Runtime/UiService.cs` (`UiService : IUiServiceInit`)
+  - Owns configs, loaded presenter instances, visible list, and UI set configs.
+  - Creates a `DontDestroyOnLoad` parent GameObject named `"Ui"` and attaches `UiServiceMonoComponent` for resolution/orientation tracking.
+  - Tracks presenters as **instances**: `Dictionary<Type, IList<UiInstance>>` where each `UiInstance` stores `(Type, Address, UiPresenter)`.
+- **Public API surface**: `Runtime/IUiService.cs`
+  - Exposes lifecycle operations (load/open/close/unload) and readonly views:
+    - `VisiblePresenters : IReadOnlyList<UiInstanceId>`
+    - `UiSets : IReadOnlyDictionary<int, UiSetConfig>`
+    - `GetLoadedPresenters() : List<UiInstance>`
+  - Note: **multi-instance overloads** (explicit `instanceAddress`) exist on `UiService` (concrete type), not on `IUiService`.
+- **Configuration**: `Runtime/UiConfigs.cs` (`ScriptableObject`)
+  - Stores UI configs as `UiConfigs.UiConfigSerializable` (address + layer + type name) and UI sets as `UiSetConfigSerializable` containing `UiSetEntry` items.
+  - Use the specialized subclasses (each has `CreateAssetMenu`): `AddressablesUiConfigs` (default), `ResourcesUiConfigs`, `PrefabRegistryUiConfigs` (embedded prefab registry).
+  - Note: `UiConfigs` is `abstract` to prevent accidental direct usage—always use one of the specialized subclasses.
+- **UI Sets**: `Runtime/UiSetConfig.cs`
+  - `UiSetEntry` stores:
+    - presenter type as `AssemblyQualifiedName` string
+    - optional `InstanceAddress` (empty string means default instance)
+  - `UiSetConfig` is the runtime shape: `SetId` + `UiInstanceId[]`.
+- **Presenter pattern**: `Runtime/UiPresenter.cs`
+  - Lifecycle hooks: `OnInitialized`, `OnOpened`, `OnClosed`, `OnOpenTransitionCompleted`, `OnCloseTransitionCompleted`.
+  - Typed presenters: `UiPresenter<T>` with a `Data` property that triggers `OnSetData()` on assignment (works during `OpenUiAsync(..., initialData, ...)` or later updates).
+  - Presenter features are discovered via `GetComponents(_features)` at init time and are notified in the open/close lifecycle.
+  - **Transition tasks**: `OpenTransitionTask` and `CloseTransitionTask` are public `UniTask` properties that complete when all transition features finish.
+  - **Visibility control**: `UiPresenter` is the single point of responsibility for `SetActive(false)` on close; it waits for all `ITransitionFeature` tasks before hiding.
+- **Composable features**: `Runtime/Features/*`
+  - `PresenterFeatureBase` allows attaching components to a presenter prefab to hook lifecycle.
+  - `ITransitionFeature` interface for features that provide open/close transition delays (presenter awaits these).
+  - Built-in transition features: `TimeDelayFeature`, `AnimationDelayFeature`.
+  - UI Toolkit support: `UiToolkitPresenterFeature` (via `UIDocument`) provides `AddVisualTreeAttachedListener(callback)` for safe element queries. Callback is invoked on each open because UI Toolkit recreates elements when the presenter is deactivated/reactivated.
+- **Helper views**: `Runtime/Views/*` (`GameLovers.UiService.Views`)
+  - `SafeAreaHelperView`: adjusts anchors/size based on safe area (notches).
+  - `NonDrawingView`: raycast target without rendering (extends `Graphic`).
+  - `AdjustScreenSizeFitterView`: layout fitter that clamps between min/flexible size.
+  - `InteractableTextView`: TMP link click handling.
+- **Asset loading**: `Runtime/Loaders/IUiAssetLoader.cs`
+  - `IUiAssetLoader` abstraction with multiple implementations under `Runtime/Loaders/`:
+    - `AddressablesUiAssetLoader` (default): uses `Addressables.InstantiateAsync` and `Addressables.ReleaseInstance`.
+    - `PrefabRegistryUiAssetLoader`: uses direct prefab references (useful for samples/testing). Can be initialized with a `PrefabRegistryUiConfigs` in its constructor.
+    - `ResourcesUiAssetLoader`: uses `Resources.Load`.
+  - Supports optional synchronous instantiation via `UiConfig.LoadSynchronously` (in Addressables loader).
+- **Analytics (optional)**: `Runtime/UiAnalytics.cs`
+  - `IUiAnalytics`/`UiAnalytics` track lifecycle events + basic timings; defaults to `NullAnalytics`.
+  - `UiService.CurrentAnalytics` is an **internal** static reference used by editor windows.
+
+## 3. Key Directories / Files
+- **Docs (user-facing)**: `docs/`
+  - `docs/README.md` — documentation entry point.
+- **Runtime**: `Runtime/`
+  - Entry points: `IUiService.cs`, `UiService.cs`, `UiPresenter.cs`, `UiConfigs.cs`, `UiSetConfig.cs`, `UiInstanceId.cs`.
+  - Integrations / extension points (start here when behavior differs from expectations):
+    - `Loaders/*` — **how presenter prefabs are instantiated / released**.
+      - If UI fails to load/unload, start at `Loaders/IUiAssetLoader.cs` and the active loader (`AddressablesUiAssetLoader`, `ResourcesUiAssetLoader`, `PrefabRegistryUiAssetLoader`).
+      - Loader choice is typically driven by which `UiConfigs` subclass you use (`AddressablesUiConfigs` / `ResourcesUiConfigs` / `PrefabRegistryUiConfigs`).
+    - `Features/*` — **presenter composition** (components attached to presenter prefabs).
+      - Lifecycle hooks live in `PresenterFeatureBase`; features are discovered during presenter initialization.
+      - Transition timing issues (UI not showing/hiding when expected) usually involve `ITransitionFeature` implementations (eg `TimeDelayFeature`, `AnimationDelayFeature`).
+      - UI Toolkit presenters rely on `UiToolkitPresenterFeature`; avoid querying `UIDocument.rootVisualElement` during `OnInitialized()`—use `AddVisualTreeAttachedListener(...)`.
+    - `Views/*` — **optional helper components** used by presenter prefabs (safe area, raycasts, layout fitters, TMP link clicks).
+      - If interaction/layout is off but service bookkeeping looks correct, look here before changing `UiService`.
+- **Editor**: `Editor/` (assembly: `Editor/GameLovers.UiService.Editor.asmdef`)
+  - Config editors: `UiConfigsEditorBase.cs`, `*UiConfigsEditor.cs`, `DefaultUiConfigsEditor.cs`.
+  - Debugging: `UiAnalyticsWindow.cs`, `UiServiceHierarchyWindow.cs`, `UiPresenterEditor.cs`.
+- **Samples**: `Samples~/`
+  - Demonstrates basic flows, data presenters, delay features, UI Toolkit integration, analytics.
+- **Tests**: `Tests/`
+  - `Tests/EditMode/*` — unit tests (configs, sets, analytics, loaders, core service behavior)
+  - `Tests/PlayMode/*` — integration/performance/smoke tests
+
+## 4. Important Behaviors / Gotchas
+- **Instance address normalization**
+  - `UiInstanceId` normalizes `null/""` to `string.Empty`.
+  - Prefer **`string.Empty`** as the default/singleton instance identifier.
+- **Ambiguous “default instance” calls**
+  - `UiService` uses an internal `ResolveInstanceAddress(type)` when an API is called without an explicit `instanceAddress`.
+  - If **multiple instances** exist, it logs a warning and selects the **first** instance. For multi-instance usage, prefer calling `UiService` overloads that include `instanceAddress`.
+- **Presenter self-close + destroy with multi-instance**
+  - `UiPresenter.Close(destroy: true)` now correctly uses the presenter's stored `InstanceAddress` to unload the correct instance.
+  - This works seamlessly for both singleton and multi-instance presenters.
+- **Layering**
+  - `UiService` enforces sorting by setting `Canvas.sortingOrder` or `UIDocument.sortingOrder` to the config layer when adding/loading.
+  - Loaded presenters are instantiated under the `"Ui"` root directly (no per-layer container GameObjects).
+- **UI Sets store types, not addresses**
+  - UI sets are serialized as `UiSetEntry` (type name + instance address). The default editor populates `InstanceAddress` with the **addressable address** for uniqueness.
+- **`LoadSynchronously` persistence**
+  - `UiConfig.LoadSynchronously` exists and is respected by `AddressablesUiAssetLoader`.
+  - **However**: `UiConfigs.UiConfigSerializable` currently does **not** serialize `LoadSynchronously`, so configs loaded from a `UiConfigs` asset will produce `LoadSynchronously = false` in `UiConfigs.Configs`.
+- **Static events**
+  - `UiService.OnResolutionChanged` / `UiService.OnOrientationChanged` are static `UnityEvent`s raised by `UiServiceMonoComponent`.
+  - The service does not clear listeners; consumers must unsubscribe appropriately.
+- **Disposal**
+  - `UiService.Dispose()` closes all visible UI, attempts to unload all loaded instances, clears collections, and destroys the `"Ui"` root GameObject.
+- **Editor debugging tools**
+  - Some editor windows toggle `presenter.gameObject.SetActive(...)` directly for convenience; this may not reflect in `IUiService.VisiblePresenters` since it bypasses `UiService` bookkeeping.
+- **UI Toolkit visual tree timing and element recreation**
+  - `UIDocument.rootVisualElement` may not be ready when `OnInitialized()` is called on a presenter.
+  - UI Toolkit **recreates visual elements** when the presenter GameObject is deactivated/reactivated (close/reopen cycle), `AddVisualTreeAttachedListener(callback)` invokes  on **each open** to handle element recreation.
+
+## 5. Coding Standards (Unity 6 / C# 9.0)
+- **C#**: C# 9.0 syntax; no global `using`s; keep **explicit namespaces**.
+- **Assemblies**
+  - Runtime code should avoid `UnityEditor` references; editor-only tooling belongs under `Editor/` and `GameLovers.UiService.Editor.asmdef`.
+  - If you must add editor-only code near runtime types, guard it with `#if UNITY_EDITOR` and keep it minimal.
+- **Async**
+  - Use `UniTask`; thread `CancellationToken` through async APIs where available.
+- **Memory / allocations**
+  - Avoid per-frame allocations; keep API properties allocation-free (see `UiService` read-only wrappers for `VisiblePresenters` and `UiSets`).
+
+## 6. External Package Sources (for API lookups)
+When you need third-party source/docs, prefer the locally-cached UPM packages:
+- Addressables: `Library/PackageCache/com.unity.addressables@*/`
+- UniTask: `Library/PackageCache/com.cysharp.unitask@*/`
+
+## 7. Dev Workflows (common changes)
+- **Add a new presenter**
+  - Create a prefab with a component deriving `UiPresenter` (or `UiPresenter<T>`).
+  - Ensure it has a `Canvas` or `UIDocument` if you want layer sorting to apply.
+  - Mark the prefab Addressable and set its address.
+  - Add/update the entry in `UiConfigs` (menu: `Tools/UI Service/Select UiConfigs`).
+- **Add / update UI sets**
+  - The default `UiConfigs` inspector uses `DefaultUiSetId` (out-of-the-box).
+  - To customize set ids, create your own enum and your own `[CustomEditor(typeof(UiConfigs))] : UiConfigsEditor<TEnum>`.
+- **Add multi-instance flows**
+  - Use `UiInstanceId` (default = `string.Empty`) when you need to track instances externally.
+  - Presenters know their own instance address via the internal `InstanceAddress` property; `Close(destroy: true)` unloads the correct instance.
+- **Add a presenter feature**
+  - Extend `PresenterFeatureBase` and attach it to the presenter prefab.
+  - Features are discovered via `GetComponents` at init time and notified during open/close.
+  - For features with transitions (animations, delays): implement `ITransitionFeature` so the presenter can await your `OpenTransitionTask` / `CloseTransitionTask`.
+- **Change loading strategy**
+  - Prefer using one of the built-in loaders (`AddressablesUiAssetLoader`, `PrefabRegistryUiAssetLoader`, `ResourcesUiAssetLoader`) or extending `IUiAssetLoader` for custom needs.
+- **Update docs/samples**
+  - User-facing docs live in `docs/` and should be updated when behavior/API changes.
+  - If you add a new core capability, consider adding/adjusting a sample under `Samples~/`.
+
+## 8. Update Policy
+Update this file when:
+- Public API changes (`IUiService`, `IUiServiceInit`, presenter lifecycle, config formats)
+- Core runtime systems/features are introduced/removed (features, views, analytics, multi-instance)
+- Editor tooling changes how configs or sets are generated/serialized

AGENTS.md.meta

@@ -4,6 +4,50 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html)
 
+## [1.1.0] - 2026-01-06
+
+**New**:
+- Added `OpenUiSetAsync(int setId, CancellationToken)` method to `IUiService` for opening all UI presenters in a set with proper address handling, ensuring compatibility with `CloseAllUiSet` and `UnloadUiSet`
+- Added `OnOpenTransitionCompleted()` and `OnCloseTransitionCompleted()` lifecycle hooks to `UiPresenter` for reacting after all transition animations/delays complete
+- Added comprehensive test suite:
+  - Unit tests for `UiAnalytics`, `UiConfig`, `UiInstanceId`, `UiServiceCore`, `UiSetConfig`
+  - PlayMode integration tests for multi-instance, loading, open/close, and UI set management
+  - Performance and smoke tests
+  - Feature-specific tests for `AnimationDelayFeature`, `TimeDelayFeature`, and `PresenterFeatureBase`
+- Added `ITransitionFeature` interface for features that provide open/close transition delays
+- Added `OpenTransitionTask` and `CloseTransitionTask` public properties on `UiPresenter` for awaiting transition completion externally
+- Added `AGENTS.md` documentation for AI coding agents
+- Added structured documentation under `docs/` folder with separate pages for getting started, core concepts, API reference, advanced topics, and troubleshooting
+- Added multiple new samples to the package library
+- Added multiple `IUiAssetLoader` implementations to support different asset loading scenarios:
+  - `AddressablesUiAssetLoader` (default): Integration with Unity Addressables.
+  - `PrefabRegistryUiAssetLoader`: Simple loader for direct prefab references (useful for testing and samples).
+  - `ResourcesUiAssetLoader`: Support for loading from Unity's `Resources` folder.
+- Added `AddressablesUiConfigs`, `ResourcesUiConfigs`, `PrefabRegistryUiConfigs`, `ResourcesUiConfigsEditor`, `AddressablesUiConfigsEditor` and `PrefabRegistryUiConfigsEditor` for managing UI configurations.
+
+**Changed**:
+- **BREAKING**: Made `UiConfigs` class `abstract` to enforce usage of specialized subclasses (`AddressablesUiConfigs`, `ResourcesUiConfigs`, `PrefabRegistryUiConfigs`) and prevent runtime errors from misconfiguration
+- **BREAKING**: Removed `IPresenterFeature` interface; features now extend `PresenterFeatureBase` directly
+- **BREAKING**: Renamed `UiAssetLoader` to `AddressablesUiAssetLoader` to reflect its specific loading mechanism.
+- **BREAKING**: Renamed `UiConfig.AddressableAddress` to `UiConfig.Address` for loader-agnosticism
+- Changed `UiPresenter<T>.Data` property to have a public setter that automatically triggers `OnSetData()` when assigned
+- Refactored `TimeDelayFeature` and `AnimationDelayFeature` to no longer call `gameObject.SetActive(false)` directly; visibility is now controlled solely by `UiPresenter`
+- Refactored `UiPresenter.InternalOpen()` and `InternalClose()` to use internal async processes that await `ITransitionFeature` tasks
+- Refactored `AnimationDelayFeature` and `TimeDelayFeature` to use `Presenter.NotifyOpenTransitionCompleted()` and `Presenter.NotifyCloseTransitionCompleted()` instead of internal events
+- Removed `OnOpenCompletedEvent` and `OnCloseCompletedEvent` internal events from delay features
+- Updated all samples to use UI buttons instead of input system dependencies for better project compatibility
+
+**Fixed**:
+- Fixed `AnimationDelayFeature` animation playback logic - was incorrectly checking `!_introAnimationClip` instead of `_introAnimationClip != null`
+- Fixed `UiPresenterEditor` play-mode buttons to properly call `InternalOpen()` and `InternalClose()` instead of just toggling `gameObject.SetActive()`
+- Fixed delay features to work correctly when tests run together (UniTaskCompletionSource lifecycle)
+- Fixed null checks in delay features using explicit null comparisons instead of null-conditional operators for Unity object compatibility
+- Fixed inconsistent lifecycle where `OnOpenTransitionCompleted`/`OnCloseTransitionCompleted` were only called when features existed
+- Fixed split responsibility for visibility control where both `UiPresenter` and features could call `SetActive(false)`, allowing now to properly close the presenters in all scenarios
+- Fixed `LoadUiAsync` visibility state inconsistency where calling it on an already-visible presenter with `openAfter=false` would disable the GameObject but not update `VisiblePresenters`, causing subsequent `OpenUiAsync` calls to fail silently
+- Fixed multi-instance ambiguity when calling `Close(destroy: true)` from within a presenter and now correctly unloads the specific instance instead of potentially unloading the wrong one
+- Fixed UI Toolkit timing issue where element queries in `OnInitialized()` would fail because the visual tree was not yet attached to a panel
+
 ## [1.0.0] - 2025-11-04
 
 **New**: