Add [SerializeReference] dropdown, repair and migration toolkit

.claude/hooks/rebuild-analyzers-on-change.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# PostToolUse hook: rebuild the Roslyn analyzer after edits inside the analyzer
+# project (a git submodule), then redeploy the DLL into the Unity package.
+# The submodule has no Directory.Build.targets on purpose (it stays independent
+# of this repo's layout), so the copy step lives here.
+#
+# Path-scoped on purpose:
+#   - Triggers ONLY for *.cs under Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/
+#   - Skips the Tests and Sample projects.
+#
+# Build success -> exit 0 (silent).
+# Path mismatch -> exit 0 (silent).
+# Build failure -> exit 2 with stderr piped through, so the assistant sees it.
+
+set -uo pipefail
+
+file_path=$(jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+case "$file_path" in
+  */Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/*.cs) ;;
+  *) exit 0 ;;
+esac
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+dotnet build \
+  Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers.csproj \
+  -c Release --nologo -v quiet 1>&2 || exit 2
+
+cp Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/bin/Release/netstandard2.0/Aspid.FastTools.Analyzers.dll \
+   Aspid.FastTools/Packages/tech.aspid.fasttools/Aspid.FastTools.Analyzers.dll 1>&2 || exit 2

.claude/settings.json

@@ -18,6 +18,10 @@
           {
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/rebuild-generators-on-change.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/rebuild-analyzers-on-change.sh\""
           }
         ]
       }

.claude/skills/build-analyzer/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: build-analyzer
+description: Build the Roslyn analyzer submodule and deploy the resulting DLL into the Unity package
+user-invocable: true
+---
+
+Build the Aspid.FastTools analyzer (git submodule) and deploy to Unity:
+
+1. If `Aspid.FastTools.Analyzers/` is empty, run `git submodule update --init` first
+2. Run `dotnet build Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers.csproj -c Release` from the repository root
+3. Run `dotnet test Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers.sln -c Release` and stop if any test fails
+4. Copy `Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/Aspid.FastTools.Analyzers/bin/Release/netstandard2.0/Aspid.FastTools.Analyzers.dll` to `Aspid.FastTools/Packages/tech.aspid.fasttools/Aspid.FastTools.Analyzers.dll`
+5. Report the result: build/test output, any errors, and confirm the DLL was copied successfully
+
+Note: diagnostic IDs use the `AFT*` prefix. After bumping the submodule commit, remember the gitlink change in the superproject (`git add Aspid.FastTools.Analyzers`).
+
+Arguments: $ARGUMENTS (optional: pass `Debug` to build in Debug configuration instead of Release)

.gitignore

@@ -2,6 +2,7 @@
 .worktrees/
 .claude/worktrees/
 .zed/
+.DS_Store
 
 # UPM convention: `Samples~` is hidden from Unity importer but must be tracked.
 # Override global `*~` ignore.

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "Aspid.FastTools.Analyzers"]
+	path = Aspid.FastTools.Analyzers
+	url = https://github.com/VPDPersonal/Aspid.FastTools.Analyzers.git

Aspid.FastTools/.gitignore

@@ -78,6 +78,16 @@ crashlytics-build.properties
 /[Aa]ssets/[Tt]utorialInfo.meta
 /[Aa]ssets/[Tt]utorialInfo/*
 
+# Package samples imported into the dev project via Package Manager.
+# Source of truth is the package's `Samples~/`; the imported copy is local-only.
+/[Aa]ssets/[Ss]amples/
+/[Aa]ssets/[Ss]amples.meta
+
+# Auto-generated tool settings created by optional Editor packages
+# (Project Auditor, Timeline). Default values only, dev-project-local.
+/[Pp]roject[Ss]ettings/ProjectAuditorSettings.asset
+/[Pp]roject[Ss]ettings/TimelineSettings.asset
+
 # OS generated
 .DS_Store
 ._*

Aspid.FastTools/Packages/manifest.json

@@ -48,5 +48,8 @@
     "com.unity.modules.vr": "1.0.0",
     "com.unity.modules.wind": "1.0.0",
     "com.unity.modules.xr": "1.0.0"
-  }
+  },
+  "testables": [
+    "tech.aspid.fasttools"
+  ]
 }

Aspid.FastTools/Packages/tech.aspid.fasttools/Documentation/EN/README.md

@@ -17,6 +17,7 @@
 - **Features**
   - [ProfilerMarker](#profilermarker)
   - [Serializable Type System](#serializable-type-system)
+  - [SerializeReference Selector](#serializereference-selector)
   - [Enum System](#enum-system)
   - [ID System (Beta)](#id-system-beta)
   - [SerializedProperty Extensions](#serializedproperty-extensions)
@@ -247,6 +248,24 @@ public sealed class AbilitySelector : MonoBehaviour
 
 > The complete sample — `Ability` / `AbilitySelector` / `EnemyBase` and their subclasses — ships in the `Types` sample (Package Manager → Aspid.FastTools → Samples).
 
+Decorate a candidate type with `[TypeSelectorDisplay]` to tune how it appears in the picker — an editor-only attribute (`[Conditional("UNITY_EDITOR")]`) in `Aspid.FastTools.Types` that carries no runtime cost:
+
+```csharp
+using Aspid.FastTools.Types;
+
+// Rename the type in the picker, place it under an explicit group, give it a tooltip and an icon:
+[TypeSelectorDisplay(Name = "Damage ×", Group = "Combat/Modifiers",
+    Tooltip = "Scales incoming damage", Icon = "d_ScriptableObject Icon")]
+public sealed class DamageModifier { }
+```
+
+| Member | Description |
+|--------|-------------|
+| `Name` | Display name shown instead of the type's short name — in the picker rows and in the closed dropdown's caption. Search still matches the real type name too, and the hover tooltip keeps revealing the full `Namespace.Class, Assembly` identity. `null` or whitespace means no override. |
+| `Group` | Explicit picker path with `/` separating levels (e.g. `"Combat/Melee"`). **Replaces** the type's namespace placement — the type appears only under this path, and path segments are shared between types. `null` or whitespace keeps the namespace placement. |
+| `Tooltip` | Tooltip shown when hovering the type's row. `null` means no tooltip override. |
+| `Icon` | Editor icon shown left of the label — an `EditorGUIUtility.IconContent` name, a project-relative asset path with extension (loaded via `AssetDatabase`), or a `Resources` texture path without extension. `null` means no icon. |
+
 ---
 
 ### Type Selector Window
@@ -258,6 +277,7 @@ The Inspector shows a button that opens a searchable popup window with:
 - Keyboard navigation (Arrow keys, Enter, Escape)
 - Navigation history (back button)
 - Assembly disambiguation for types with identical names
+- **Favorites** and **Recent** sections on the root page: a hover-revealed ★ toggle pins a type to Favorites, and the last 8 picked types are kept under Recent (both persisted per project, hidden while searching)
 
 ![aspid_fasttools_type_selector_window.png](../Images/aspid_fasttools_type_selector_window.png)
 
@@ -323,6 +343,97 @@ public sealed class TankEnemy : EnemyBase
 
 ---
 
+## SerializeReference Selector
+
+A drop-in type-picker dropdown for `[SerializeReference]` fields. Add `[TypeSelector]` next to `[SerializeReference]` and the Inspector replaces the default managed-reference UI with the same searchable, hierarchical picker used by `SerializableType`. You choose which concrete implementation of the field's type is instantiated, right in the Inspector; `<None>` clears the reference.
+
+```csharp
+using System;
+using UnityEngine;
+using System.Collections.Generic;
+using Aspid.FastTools.Types;
+
+public interface IWeapon
+{
+    void Fire();
+}
+
+[Serializable]
+public sealed class Pistol : IWeapon
+{
+    [SerializeField] [Min(0)] private int _damage = 10;
+
+    public void Fire() => Debug.Log($"Pistol: {_damage} dmg");
+}
+
+[Serializable]
+public sealed class Railgun : IWeapon
+{
+    [SerializeField] [Min(0)] private float _chargeTime = 1.5f;
+
+    public void Fire() => Debug.Log($"Railgun charged for {_chargeTime}s");
+}
+
+public sealed class Loadout : MonoBehaviour
+{
+    [SerializeReference] [TypeSelector]
+    private IWeapon _primary;
+
+    [SerializeReference] [TypeSelector]
+    private List<IWeapon> _sidearms;
+}
+```
+
+The attribute is editor-only (`[Conditional("UNITY_EDITOR")]`) and carries no runtime cost. It works on single fields, arrays, and `List<T>`, in both IMGUI and UIToolkit inspectors.
+
+### Capabilities
+
+| Capability | What it does |
+|---|---|
+| **Pick an implementation** | The list shows the concrete, non-`UnityEngine.Object` classes assignable to the field's type. `[TypeSelector(typeof(IMelee))]` narrows it to `IMelee` implementations. |
+| **Inline inspector** | The selected instance's serialized fields are drawn under a foldout. |
+| **Open generics** | `Modifier<T>` and the like: arguments are inferred from a closed-generic field, or picked on a second page inside the picker. |
+| **Data preserved** | Switching type carries over fields shared by name and serialized shape instead of resetting them to defaults. |
+| **Copy / Paste** | Right-click the header to copy the value and paste it as an independent instance into any compatible field. |
+| **Multi-object editing** | A mixed selection shows a mixed dropdown; picking a type or pasting applies an independent instance to each object in one Undo group. |
+| **Compile-time checks** | Roslyn analyzer: `AFT0004` (error) — the type derives from `UnityEngine.Object`; `AFT0005` (warning) — the picker would be empty. |
+
+### Repairing broken references
+
+| Case | Fix |
+|---|---|
+| **Missing type** (renamed or deleted) | A yellow notice instead of a silent clear. The underlined **Fix** opens the picker and re-points the type while keeping its data — at any depth, in saved assets and live in Prefab Mode. |
+| **Smart Fix** | Next to **Fix**, suggests the most likely replacement (`[MovedFrom]`, a different namespace/assembly, casing, a near-miss name) and applies it in one click — never automatically. |
+| **Shared reference** (two fields share one instance) | Flagged with a notice; **Make unique** splits it into an independent copy. Duplicating a list element (Ctrl+D, `+`) no longer aliases the reference. |
+
+Bulk repair lives in two dedicated tabs:
+
+| Tab | Purpose |
+|---|---|
+| **Asset References** (`Tools → Aspid 🐍 → FastTools → Asset References`) | Maps an asset's whole managed-reference graph from its YAML — a per-component tree with field paths, shared and orphaned references, `MISSING` / `SHARED` badges, and an inline type dropdown on every card. Surfaces the missing references the Inspector cannot show. |
+| **Project References** (`Tools → Aspid 🐍 → FastTools → Project References`) | `Scan Project` sweeps every `.prefab` / `.asset` / `.unity` under `Assets/`, groups broken references by stored type, and rewrites a whole group with a single `Fix all` (plus Smart Fix). A group whose stored type matches a declared `[MovedFrom]` rename reads as a pending migration instead of a breakage — one **Migrate all** click bakes the rename into the files, after which the attribute can be removed from code. |
+
+### Project settings & the build/CI gate
+
+**`Project Settings → Aspid FastTools → SerializeReference`** exposes:
+
+| Setting | Scope | What it does |
+|---|---|---|
+| **Breakage detection** | per-user | The proactive toast + console warning when references newly become missing after a recompile / import. |
+| **Auto de-alias duplicated list elements** | committed | A duplicated list element gets its own instance instead of sharing the original's reference id. |
+| **Build / CI gate** | committed | `Off` / `Warn` / `Fail`: at player-build time, log or abort on missing (and, for CI, unset-required) managed references. |
+| **Excluded scan folders** | committed | Paths skipped by every project scan. |
+
+Committed values live in `ProjectSettings/SerializeReferenceSharedSettings.asset` — commit it so teammates and CI behave identically; breakage detection stays per-machine (`EditorPrefs`). Rid colours are not a setting — a shared reference is always colour-coded by id, since matching colours is what lets you tell which fields share an instance at a glance.
+
+The same options are mirrored in the window's **Settings** tab (`Tools → Aspid 🐍 → FastTools → Settings`) and at **`Preferences → Aspid FastTools`**, alongside the picker's per-user preferences: a **Favorites** section toggle, a **Recent items** capacity slider (0–20; 0 hides the section and pauses recording without wiping history), a **Saved lists** row that clears the stored Favorites / Recent, an **Appearance** section (editor-theme override `StyleSheet` with **Create template…**) and a **Welcome** auto-show toggle. Every row carries a scope stripe — green for committed values, blue for per-user — and a pinned footer offers **Reset to defaults** separately per scope (saved Favorites / Recent lists survive a reset). All surfaces stay in live sync.
+
+For headless CI, `SerializeReferenceCiGate.RunCheck` (invoked via `-batchmode -executeMethod`) writes a report and honours the committed gate severity: `Off` skips the check, `Warn` logs but exits 0, `Fail` exits non-zero when violations exist. `-srGateRequired` also flags unset `[TypeSelector(Required = true)]` fields across prefabs, ScriptableObjects and scenes (scenes are checked for top-level required fields via a pure-YAML pass); the per-run flags `-srGateWarnOnly` / `-srGateFail` override the committed severity.
+
+> The full sample — `Loadout` / `IWeapon` / `Modifier<T>` and the missing-reference repair scenarios — ships in the `SerializeReferences` sample (Package Manager → Aspid.FastTools → Samples). A step-by-step walkthrough lives in that sample's `TUTORIAL.md`.
+
+---
+
 ## Enum System
 
 Provides serializable enum-to-value mappings configurable from the Inspector.