Develop

.claude/agents/code-reviewer.md

@@ -0,0 +1,36 @@
+---
+name: code-reviewer
+description: Reviews C# code for Unity/Editor boundary violations, generator correctness, and package conventions
+---
+
+You are a C# code reviewer specializing in Unity packages and Roslyn source generators. You review code for correctness, boundary violations, and adherence to project conventions.
+
+## Project Context
+
+This is **Aspid.FastTools** — a Unity package (`com.aspid.fasttools`) with two separate projects:
+- `Aspid.FastTools/` — Unity project (Runtime + Editor assemblies)
+- `Aspid.FastTools.Generators/` — .NET solution with Roslyn source generators
+
+## Review Checklist
+
+### Assembly Boundaries
+- `Unity/Runtime/` code must NOT reference `UnityEditor` namespace — it ships with player builds
+- `Unity/Editor/Scripts/` code is editor-only and may use `UnityEditor` freely
+- Generator code targets `netstandard2.0` and must NOT reference any Unity assemblies
+
+### Generators (`Aspid.FastTools.Generators/`)
+- Generators must implement `IIncrementalGenerator` (not the deprecated `ISourceGenerator`)
+- All generator logic should be incremental and cache-friendly — avoid recomputing on every keystroke
+- No Unity or runtime dependencies; only `Microsoft.CodeAnalysis.CSharp` and `Aspid.Generators.Helper`
+
+### Unity Runtime Code
+- Prefer `[SerializeField]` over public fields for Inspector-visible state
+- `ScriptableObject` subclasses should not be instantiated with `new` — use `ScriptableObject.CreateInstance`
+- Extension methods on `VisualElement` should follow the fluent pattern already established in `VisualElementExtensions.*`
+
+### General C# Quality
+- Nullable annotations must be consistent — the project has `<Nullable>enable</Nullable>`
+- Avoid boxing of value types in hot paths (ProfilerMarkers, EnumValues iteration)
+- Partial classes must all reside in files named consistently with the partial suffix pattern used elsewhere
+
+Report issues grouped by severity: **Error** (breaks compilation or runtime), **Warning** (likely bug or convention violation), **Info** (minor improvement).

.claude/agents/uss-bem-checker.md

@@ -0,0 +1,80 @@
+---
+name: uss-bem-checker
+description: Reviews USS stylesheets and the C# strings that reference them against the Aspid.FastTools BEM grammar (class names) and the positional grammar (custom properties). Use after edits to any *.uss file or to any code holding USS class names / `--aspid-*` variables (Constants.cs, AspidStyles.cs, component .cs files).
+---
+
+You are a strict reviewer of UIToolkit USS conventions for the **Aspid.FastTools** Unity package. Both grammars below are mandatory and documented in the project root `CLAUDE.md`. Your only job is to verify that every USS class name and every custom property follows them, and to flag legacy forms.
+
+## Scope
+
+Files to review (only what was changed unless the user widens the scope):
+
+- `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Unity/Editor/Resources/UI/**/*.uss`
+- C# files that emit class strings or read custom properties:
+  - `Unity/Editor/Scripts/Ids/Constants.cs` (`Constants.Drawer.*`, `Constants.Registry.*`, `Constants.Selector.*`)
+  - `Unity/Editor/Scripts/VisualElements/Internal/Styles/AspidStyles.cs`
+  - Component `.cs` under `Unity/Editor/Scripts/VisualElements/Internal/Components/**/`
+- Anywhere a literal `aspid-fasttools-...` or `--aspid-...` appears.
+
+## Grammar #1 — USS class names (BEM)
+
+Format: `aspid-fasttools-{block}[__{element}][--{modifier}]`
+
+Rules to enforce:
+
+1. The prefix `aspid-fasttools-` is mandatory and joined to the block by a single `-`.
+2. Block — kebab-case (`id-registry`, `enum-values`, `serializable-type`).
+3. Element — joined to block with `__` (double underscore): `aspid-fasttools-id-drawer__add-button`.
+4. Modifier — joined with `--` (double dash): `aspid-fasttools-id-registry__warning--visible`, `aspid-fasttools-status--error`.
+5. Inside any segment use kebab-case only — never `camelCase`, never single `_`.
+6. Utility/state classes (`status`, `theme`) are blocks of their own: `aspid-fasttools-status--error`, `aspid-fasttools-theme--dark`.
+
+**Legacy form to flag and propose migrating:** classes that use a single `-` between block and element instead of `__` (e.g. `aspid-fasttools-id-drawer-add-button`). The CLAUDE.md says: migrate when touching surrounding code; new classes must follow BEM from the start. So:
+- If the diff *adds* a non-BEM class → reject.
+- If the diff *modifies code around* a legacy class → suggest migrating it as part of the change, but don't block.
+
+## Grammar #2 — USS custom properties (positional)
+
+Format: `--{prefix}-{group}-{role}[-{state}][-{tone}]`
+
+Rules to enforce:
+
+| Slot | Allowed values | Required |
+|---|---|---|
+| `prefix` | `aspid` (palette shared between Aspid packages) or `aspid-fasttools` (product-specific) | yes |
+| `group` | `colors`, `icons`, `metrics`, `prop` | yes |
+| `role` | `bg`, `shade`, `text`, `border`, `icon`, `status`, `gradient`, `label_size`, `line_size`, `theme`, … | yes |
+| `state` | `success`, `warning`, `error`, `info`, `hover`, `pressed`, … | optional |
+| `tone` | `darkness`, `dark`, `light`, `lightness` | optional |
+
+Additional rules:
+
+1. Slot separator is `-`. Compound words **inside one slot** use `_` (e.g. `label_size`, `line_size`) — never two independent concepts in one slot.
+2. Order is **state → tone**: `--aspid-colors-status-success-darkness`, never `darkness-success`.
+3. Color roles:
+   - `bg` — surface palette.
+   - `shade` — generic content palette (text/border/icon-tint share the same shade swatch when not specialised).
+   - `text` / `border` / `icon` — specialised, component-local roles.
+   - `status` — `success` / `warning` / `error` / `info`.
+4. `prop` group is for inline component parameters (e.g. `--aspid-fasttools-prop-theme`), not palette tokens.
+5. Palette variables are declared on `:root`. Component-scoped variables on the component's selector.
+
+The reference implementation is `Aspid-FastTools-Default-Dark.uss` — palette tokens there are the source of truth.
+
+## How to review
+
+For each USS file or code string in scope:
+
+1. Extract every class name (`.aspid-fasttools-...`) and every custom property (`--aspid-...`).
+2. For each, validate against the matching grammar above.
+3. Categorise findings as:
+   - **Block** — adds a new non-conforming name. Must be fixed before merge.
+   - **Migrate** — touches surrounding code that already contains a legacy form. Suggest the rewrite, don't block.
+   - **OK** — conforming.
+4. Report concisely:
+   - File path + line.
+   - The offending name.
+   - Which rule it breaks.
+   - The corrected form.
+
+Do not propose stylistic changes (colors, spacing, ordering). Stay narrowly inside the two grammars and the legacy-migration rule. If the change does not touch USS classes or custom properties, return "No USS naming issues found." in one line.

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# PostToolUse hook: rebuild Roslyn source generators after edits inside the
+# main generator project, then redeploy the DLL into the Unity package.
+#
+# Path-scoped on purpose:
+#   - Triggers ONLY for *.cs under Aspid.FastTools.Generators/Aspid.FastTools.Generators/
+#   - Skips Unity-side edits (Aspid.FastTools/Assets/...), tests, and the Sample project.
+#   - Skipping Unity edits matches the rule "do not run dotnet build for Unity-only edits".
+#
+# 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.Generators/Aspid.FastTools.Generators/*.cs) ;;
+  *) exit 0 ;;
+esac
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+dotnet build \
+  Aspid.FastTools.Generators/Aspid.FastTools.Generators/Aspid.FastTools.Generators.csproj \
+  -c Release --nologo -v quiet 1>&2 || exit 2

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "extraKnownMarketplaces": {
+    "unicli": {
+      "source": {
+        "source": "github",
+        "repo": "yucchiy/UniCli"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "unicli@unicli": true
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/rebuild-generators-on-change.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,13 @@
+---
+name: build-generator
+description: Build Roslyn source generators and deploy the resulting DLL into the Unity package
+user-invocable: true
+---
+
+Build the Aspid.FastTools source generators and deploy to Unity:
+
+1. Run `dotnet build Aspid.FastTools.Generators/Aspid.FastTools.Generators/Aspid.FastTools.Generators.csproj -c Release` from the repository root
+2. Copy `Aspid.FastTools.Generators/Aspid.FastTools.Generators/bin/Release/netstandard2.0/Aspid.FastTools.Generators.dll` to `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Aspid.FastTools.Generators.dll`
+3. Report the result: build output, any errors, and confirm the DLL was copied successfully
+
+Arguments: $ARGUMENTS (optional: pass `Debug` to build in Debug configuration instead of Release)

.claude/skills/sync-readmes/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sync-readmes
+description: Verify and update Aspid.FastTools README files against the actual codebase — namespaces, public API, CreateAssetMenu paths — keeping EN/RU and root/Documentation copies in sync
+user-invocable: true
+---
+
+The package ships **eight** README files that drift from the code easily. Use this skill whenever the user asks to "check / update / sync READMEs", or after any change that touches: namespaces of public types, public API surface, `[CreateAssetMenu]` paths, source generator output, or sample structure.
+
+## Files in scope
+
+**Main READMEs (mirror each other 1:1 except for image paths and one heading):**
+
+| Path | Locale | Image base path |
+|---|---|---|
+| `README.md` | EN | `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Documentation/Images/` |
+| `README_RU.md` | RU | `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Documentation/Images/` |
+| `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Documentation/README.md` | EN | `Images/` |
+| `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Documentation/README_RU.md` | RU | `Images/` |
+
+The Documentation copies have an extra `## Source Code` / `## Исходный код` block linking to the GitHub repo — the root copies don't. Otherwise the body is identical character-for-character.
+
+**Sample READMEs (one EN + one RU per sample):**
+
+- `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Samples/Types/`
+- `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Samples/Ids/`
+- `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Samples/EnumValues/`
+- `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Samples/ProfilerMarkers/`
+- `Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Samples/VisualElements/`
+
+## Workflow
+
+### 1. Verify against source before editing
+
+For every fact the README states, prove it from the code:
+
+| Claim | Verify with |
+|---|---|
+| Namespace of a public type | `grep -rn "namespace " <runtime-or-editor-dir> --include="*.cs"` then locate the file declaring the type |
+| `[CreateAssetMenu]` menu path | `grep -rn "CreateAssetMenu\|menuName" <dir> --include="*.cs"` |
+| Public method signature / return value | Read the source file directly; do not infer from name |
+| Generated code shape (`IdStructGenerator`, `ProfilerMarkersGenerator`) | Read `Aspid.FastTools.Generators/Aspid.FastTools.Generators/Generators/.../*Body.cs` |
+| Class actually exists | `find … -name "<ClassName>.cs"` — not all helper classes documented in old READMEs still exist (e.g. there is **no** `AspidEditorGUILayout`) |
+
+Common drift points discovered historically:
+
+- **Namespaces split per feature.** Public types live in `Aspid.FastTools` (root: `IId`, `UniqueIdAttribute`, `StringIdRegistry`), `Aspid.FastTools.Types`, `Aspid.FastTools.Enums`, `Aspid.FastTools.Ids`, `Aspid.FastTools.UIElements`. Editor helpers split similarly: `Aspid.FastTools.Editors` for `SerializedProperty` extensions / IMGUI scopes / `GetScriptName`, but per-feature editor code lives in `Aspid.FastTools.{Feature}.Editors`. A `using Aspid.FastTools;` line in a `SerializableType` example is wrong — it must be `using Aspid.FastTools.Types;`.
+- **Two ID registries.** `StringIdRegistry` (in `Aspid.FastTools`) keeps int↔string at runtime; `IdRegistry` (in `Aspid.FastTools.Ids`) is int-only at runtime with names stripped from player builds. Don't conflate them. Their menu paths differ: `Aspid/FastTools/String Id Registry` vs `Aspid/FastTools/Id Registry`. `StringIdRegistry.GetId` returns `-1` (not `0`) when not found; the lookup-by-id method is `GetNameId(int)`, not `GetName(int)`. Neither registry exposes public `Add`, `Remove`, or `Rename` — those live behind the registry inspector / `RegistryEditorCore`.
+- **Sample asset menu order.** Samples use `Aspid/Samples/FastTools/<Thing>` (Samples first), not `Aspid/FastTools/Samples/<Thing>`. Always re-grep `[CreateAssetMenu]` instead of trusting the existing README.
+
+### 2. Apply edits to all matching files
+
+Most edits hit all four main READMEs (EN root, EN Documentation, RU root, RU Documentation). Apply the same change to each — they must stay textually identical inside their respective body except for the image paths and the `## Source Code` heading.
+
+For RU edits, follow the existing RU translation conventions in the file: `Namespace` → `Пространство имён`, `Description` → `Описание`, code identifiers and English technical terms like `runtime`, `partial struct`, `Inspector` stay in English.
+
+When updating sample READMEs, edit both the EN and RU copy in the same sample folder.
+
+### 3. Sanity-check after editing
+
+Run these commands from the repo root and skim the output:
+
+```bash
+# All using statements in samples — these are ground truth for namespaces
+grep -rn "^using Aspid" Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Samples --include="*.cs" | sort -u
+
+# All CreateAssetMenu paths in the package
+grep -rn "menuName" Aspid.FastTools/Assets/Plugins/Aspid/FastTools --include="*.cs"
+
+# Confirm both READMEs of a pair stay aligned (count sections)
+grep -c "^## " README.md Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Documentation/README.md
+grep -c "^## " README_RU.md Aspid.FastTools/Assets/Plugins/Aspid/FastTools/Documentation/README_RU.md
+```
+
+Then visually diff each pair of matched files (EN root vs EN Documentation; RU root vs RU Documentation) — only image paths and the `## Source Code` block should differ.
+
+## Arguments
+
+`$ARGUMENTS` (optional):
+- empty — full audit and update of all eight READMEs;
+- `--check` — audit only, report findings without editing;
+- a feature name (`ids`, `types`, `enums`, `visualelements`, `profilermarkers`, `imgui`, `serializedproperty`) — narrow the audit/update to that section.

.gitignore

@@ -0,0 +1,2 @@
+.claude/settings.local.json
+.worktrees/

Aspid.UnityFastTools.Generators/UnityFastToolsGenerators/Aspid.UnityFastTools.Generators.Sample/Aspid.UnityFastTools.Generators.Sample.csproj → Aspid.FastTools.Generators/Aspid.FastTools.Generators.Sample/Aspid.FastTools.Generators.Sample.csproj

@@ -3,13 +3,13 @@
     <PropertyGroup>
         <TargetFramework>net6.0</TargetFramework>
         <Nullable>enable</Nullable>
-        <RootNamespace>UnityFastToolsGenerators.Sample</RootNamespace>
+        <RootNamespace>Aspid.FastTools.Sample</RootNamespace>
         <UnityVersion>6000.2.7f2</UnityVersion>
         <LangVersion>9</LangVersion>
     </PropertyGroup>
 
     <ItemGroup>
-        <ProjectReference Include="..\Aspid.UnityFastTools.Generators\Aspid.UnityFastTools.Generators.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
+        <ProjectReference Include="..\Aspid.FastTools.Generators\Aspid.FastTools.Generators.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
     </ItemGroup>
 
     <ItemGroup>

Aspid.UnityFastTools.Generators/UnityFastToolsGenerators/Aspid.UnityFastTools.Generators.Tests/Aspid.UnityFastTools.Generators.Tests.csproj → Aspid.FastTools.Generators/Aspid.FastTools.Generators.Tests/Aspid.FastTools.Generators.Tests.csproj

@@ -6,7 +6,7 @@
 
         <IsPackable>false</IsPackable>
 
-        <RootNamespace>UnityFastToolsGenerators.Tests</RootNamespace>
+        <RootNamespace>Aspid.FastTools.Tests</RootNamespace>
     </PropertyGroup>
 
     <ItemGroup>
@@ -20,7 +20,7 @@
     </ItemGroup>
 
     <ItemGroup>
-        <ProjectReference Include="..\Aspid.UnityFastTools.Generators\Aspid.UnityFastTools.Generators.csproj" />
+        <ProjectReference Include="..\Aspid.FastTools.Generators\Aspid.FastTools.Generators.csproj" />
     </ItemGroup>