UI Revamp and Menu addition

.cursor/rules/ui-framework.mdc

@@ -0,0 +1,27 @@
+---
+description: UI work routing — read the AI framework index first, read scoped, don't scan the whole codebase
+alwaysApply: true
+---
+
+# UI Framework: Scoped Reading
+
+For ANY UI task (components, HUD, panels, buttons, meters, menus, widgets under `Assets/UI/**`), follow this before reading code:
+
+1. **Read `AI/INDEX.md` first.** It is the router. Use its *Task → Read set* table.
+2. **Open the ONE matching per-component doc** in `AI/components/<Name>.md`. Its **Files** section lists the exact code to read.
+3. **Open only those listed files.** Do NOT grep or semantic-search `Assets/**` broadly. The docs already point to the right files.
+4. **Budget:** a normal UI task = ≤ 4 docs + ≤ 6 code files. If you exceed this, you are off-route — return to `AI/INDEX.md`.
+5. **Widen by one step only** (a component's direct dependencies listed in its doc) if truly needed — never the whole repo.
+6. If no component doc matches and the task isn't in the router table, read `AI/README.md` once, then ask which component is in scope (RULES R-21).
+
+## Authoring rules (when creating/editing UI)
+
+- Obey `AI/RULES.md` (R-01…R-36). Key ones: search before create (R-05), duplicate-before-modify (R-02/R-03), tokens/`Style1*` (R-07/R-08), **Rhythm menu bar for all setup** (R-17), **runtime layout** (R-25–R-32), **edit-mode visible + saveable UI** (R-36), **register on the UI Component Gallery board via `[UIGalleryComponent]`** (R-37), **Inspector on controller** (R-31), **compile-check** (R-29, R-33), **interactive UI: EventSystem + raycast + Play lifecycle** (R-34).
+- Every new component must match the **Score HUD standard**: … **Menus:** register under **`Rhythm → Setup …`** and **`Rhythm → Create … Demo Scene`** (`AI/WORKFLOW.md` → Rhythm menu bar). **Live access (mandatory):** every new component must be openable via **demo scene** and **UI Component Gallery board** — see `AI/WORKFLOW.md` → Live access gate. **Layout pitfalls:** `AI/WORKFLOW.md` → Runtime layout & wiring. **Scene view / save:** `AI/WORKFLOW.md` → Edit-mode visibility (R-36). **Pointer/hover/click:** `AI/WORKFLOW.md` → Interactive UI checklist (R-34).
+- After changes: update the component doc + `AI/INDEX.md` + `AI/COMPONENT_INDEX.md` (R-11), then `AI/CHANGELOG.md` (R-13).
+
+## Do NOT
+
+- Do not read all of `AI/*.md` at once "to be safe" — use the router.
+- Do not open unrelated systems (Tree, Rhythm core, PrimeTween internals) unless a component doc lists them.
+- Do not invent colors/sizes/timings — they live in `AI/TOKEN_INDEX.md`.

.gitignore

@@ -11,6 +11,9 @@
 # Get latest from https://github.com/github/gitignore/blob/main/Unity.gitignore
 #
 .utmp/
+.DS_Store
+**/.DS_Store
+.tmp_ptween/
 /[Ll]ibrary/
 /[Tt]emp/
 /[Oo]bj/

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "Unity-Extensions"]
+	path = Unity-Extensions
+	url = https://github.com/Privnoval016/Unity-Extensions.git
+[submodule "Assets/Extensions"]
+	path = Assets/Extensions
+	url = https://github.com/Privnoval016/Unity-Extensions.git

AI/COMMANDS.md

@@ -0,0 +1,201 @@
+# COMMANDS
+
+> Standard AI commands. Each command is a named, repeatable procedure an agent runs on request. Commands are the executable face of the [WORKFLOW.md](./WORKFLOW.md) procedures.
+> Related: [WORKFLOW.md](./WORKFLOW.md) · [RULES.md](./RULES.md) · [REVIEW_CHECKLIST.md](./REVIEW_CHECKLIST.md)
+
+---
+
+## Conventions
+
+- Commands are written `/command-name arg=value`.
+- Every command begins by **loading [RULES.md](./RULES.md)** and ends by **updating indexes** (R-11) where applicable.
+- If any step is ambiguous or risks a rule violation, **stop and ask** (R-21).
+- Commands never commit to Git unless the user explicitly asks (R-23).
+
+Command map:
+
+| Command | Purpose | Backing workflow |
+| --- | --- | --- |
+| `/scan-project` | Search before creating | [Search](./WORKFLOW.md#the-golden-loop-applies-to-all-workflows) |
+| `/new-component` | Create a new component | [Creating Components](./WORKFLOW.md#creating-components) |
+| `/modify-component` | Change an existing component | [Modifying Components](./WORKFLOW.md#modifying-components) |
+| `/review-component` | Run the review gate | [Reviewing Components](./WORKFLOW.md#reviewing-components) |
+| `/register-component` | Add to indexes | [Registering Components](./WORKFLOW.md#registering-components) |
+| `/update-index` | Sync indexes with reality | [Updating Documentation](./WORKFLOW.md#updating-documentation) |
+| `/archive-component` | Deprecate/retire safely | [Deprecating Components](./WORKFLOW.md#deprecating-components) |
+
+---
+
+## /scan-project
+
+**Purpose:** Search the project for anything reusable before building. Mandatory precursor to creation (R-05).
+
+**Args:** `query=<keywords>` (e.g. "progress bar", "fade rise", "gold accent").
+
+**Steps:**
+1. Load [RULES.md](./RULES.md).
+2. Search [COMPONENT_INDEX.md](./COMPONENT_INDEX.md) for components matching `query` (name, tags, description).
+3. Search [PATTERNS.md](./PATTERNS.md) for a matching blueprint.
+4. Search [ANIMATION_INDEX.md](./ANIMATION_INDEX.md) for matching motion (by effect keyword).
+5. Search [TOKEN_INDEX.md](./TOKEN_INDEX.md) for existing colors/sizes/durations.
+6. Search the codebase (`Assets/UI/**`, `Assets/**/Editor/**`) for related scripts.
+7. **Report:** closest component, closest pattern, reusable animations/tokens, and a recommendation: *reuse as-is*, *make a variant*, or *create new*.
+
+**Output:** a short findings list + recommendation. Does not modify anything.
+
+---
+
+## /new-component
+
+**Purpose:** Create a brand-new component **from a pattern** when no existing component is close enough.
+
+**Args:** `name=<Name>` `pattern=<button|card|panel|window|...>` `style=<Style1|...>` `[data=<source>]`
+
+**Steps:**
+1. Load [RULES.md](./RULES.md). Run `/scan-project query=<name/pattern>`. If a ≥~70% match exists → abort and suggest `/modify-component` or a variant (R-10).
+2. Confirm the [PATTERNS.md](./PATTERNS.md) blueprint for `pattern`.
+3. Create folders per [DIRECTORY.md](./DIRECTORY.md) (`Assets/UI/<style>/<name>/...`) using bash `mkdir -p`.
+4. Scaffold the **six files** by `cp`-ing the Score HUD set (R-03), then deleting copied `.meta` files:
+   - Controller, LayoutBuilder, EditorTools, DemoController, DemoSceneBuilder, (optional) DisplayUtil.
+5. Rename classes, `[AddComponentMenu]`, `[MenuItem]` paths, demo scene path, and fields consistently.
+6. Implement the controller contract: grouped serialized fields + `[Tooltip]`, toggles, `Initialize`, `ApplyDisplayOptions`, `OnValidate`, public setters (R-14, R-15).
+7. Implement the idempotent LayoutBuilder per [WORKFLOW.md → Runtime layout & wiring](./WORKFLOW.md#runtime-layout--wiring-mandatory) (R-19, R-25–R-28); auto-build in `Awake` when invalid.
+8. Use only tokens/style classes for visuals (R-07, R-08); reuse animations (R-09).
+9. Implement the demo (buttons + keyboard + toggles) and the demo-scene `[MenuItem]` (R-18). **Scene builder:** `Rebuild*Layout()` before `SaveScene`; **Setup menu:** find-or-create on Canvas (R-36).
+10. Verify **Scene view without Play**; compile; resolve all console errors/warnings (R-29, R-36).
+11. Add `[UIGalleryComponent("Name", UIGalleryCategory.X)]` to the controller; confirm it appears via **Rhythm → Setup UI Component Gallery** (R-37).
+12. **Live access gate (mandatory):** verify **both** paths work before handoff — (1) `Rhythm → Create <Name> Demo Scene` opens a working demo scene; (2) component appears on the UI Component Gallery board. See [WORKFLOW.md → Live access gate](./WORKFLOW.md#live-access-gate-mandatory-when-creating-a-component). **Not done** if either fails.
+13. Run `/register-component name=<Name>`.
+14. Run `/review-component name=<Name>`.
+15. Add a [CHANGELOG.md](./CHANGELOG.md) entry (R-13).
+
+**Done when:** review passes and indexes are updated.
+
+---
+
+## /modify-component
+
+**Purpose:** Change an existing component safely, preferring extension (R-06).
+
+**Args:** `name=<Name>` `change=<description>`
+
+**Steps:**
+1. Load [RULES.md](./RULES.md). Open the component's [COMPONENT_INDEX.md](./COMPONENT_INDEX.md) entry; read `Used By` / `Dependencies`.
+2. If the component is shared and the change would alter default behavior for existing users → **make a variant** (`/new-component` variant path) instead (R-01).
+3. Implement via new toggle + new code path where possible (R-06). Keep defaults backward-compatible.
+4. Keep all visuals token-driven (R-08); reuse animations (R-09).
+5. Update the demo to exercise the new behavior.
+6. If layout/lifecycle touched: follow [WORKFLOW.md → Runtime layout & wiring](./WORKFLOW.md#runtime-layout--wiring-mandatory) and [Procedural sprites](./WORKFLOW.md#procedural-sprites-checklist-r-32) (R-25–R-32).
+7. Compile; resolve console issues — **zero errors required** (R-29, R-33). If pointer UI: walk [Interactive UI checklist](./WORKFLOW.md#interactive-ui-checklist-r-34) (R-34).
+8. Bump `Version` + `Last Updated` (and animation/token entries if affected) via `/update-index`.
+9. Run `/review-component` (include §12 Runtime layout & wiring when applicable).
+10. [CHANGELOG.md](./CHANGELOG.md) entry.
+
+---
+
+## /review-component
+
+**Purpose:** Run the full quality gate.
+
+**Args:** `name=<Name>`
+
+**Steps:**
+1. Load [REVIEW_CHECKLIST.md](./REVIEW_CHECKLIST.md).
+2. Evaluate every section (Naming → Reuse, **§12 Runtime layout & wiring** when layout/lifecycle touched) and the "Score HUD standard" gate; mark Pass/Fail/N-A with rule citations.
+3. For each Fail: route to `/modify-component` and fix.
+4. Verify indexes are accurate.
+5. Produce the sign-off block (Approved / Changes Requested) and record results in the component's index notes; log notable outcomes in [CHANGELOG.md](./CHANGELOG.md).
+
+**Output:** completed checklist + sign-off. No silent fixes — list what changed.
+
+---
+
+## /register-component
+
+**Purpose:** Add a new/duplicated component to the indexes (R-11).
+
+**Args:** `name=<Name>`
+
+**Steps:**
+1. Add a detailed block + quick-lookup row to [COMPONENT_INDEX.md](./COMPONENT_INDEX.md) with **all** fields (Name, Category, Folder, Prefab, Scripts, Animations, Variants, Dependencies, Used By, Description, Status, Version, Author, Last Updated, Tags).
+2. Add any new animations to [ANIMATION_INDEX.md](./ANIMATION_INDEX.md); link reused ones and update their `Used By`.
+3. Add any new tokens to [TOKEN_INDEX.md](./TOKEN_INDEX.md) (status Live).
+4. If a new reusable shape emerged, extend [PATTERNS.md](./PATTERNS.md).
+5. Fill bidirectional `Used By` / `Dependencies`.
+
+---
+
+## /update-index
+
+**Purpose:** Re-sync indexes with the current state of the code (catch drift).
+
+**Args:** `[scope=all|component:<Name>|animations|tokens]`
+
+**Steps:**
+1. For the scope, compare index entries against the actual files (scripts present, animations used, tokens referenced).
+2. Fix stale rows: versions, `Last Updated`, dependencies, statuses.
+3. Remove nothing — deprecate instead (R-04). Flag orphaned entries for `/archive-component`.
+4. Repair broken cross-references and the README architecture map (R-12).
+5. Note significant corrections in [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## /archive-component
+
+**Purpose:** Deprecate or retire a component without breaking history (R-04).
+
+**Args:** `name=<Name>` `[replacement=<Name>]`
+
+**Steps:**
+1. Find all dependents (`Used By` + project search). If any remain and no `replacement` is given → **stop and ask** (R-21).
+2. Set `Status: Deprecated` in [COMPONENT_INDEX.md](./COMPONENT_INDEX.md) (keep the row). Add a deprecation note + `replacement` pointer.
+3. Mark code `[System.Obsolete("Use <replacement>")]` if it remains.
+4. Migrate dependents to the replacement (separate `/modify-component` runs).
+5. Only after all dependents migrate may files be removed via `git mv`/`git rm` in a clearly-logged, separate change.
+6. [CHANGELOG.md](./CHANGELOG.md) entry under `Deprecated` (and later `Removed`).
+
+---
+
+## /fix-procedural-ui *(troubleshooting)*
+
+**Purpose:** Fix square/flat procedural UI or "Inspector color changes don't apply" reports (R-30–R-32).
+
+**Args:** `component=<Name>` (default: ScoreHUD)
+
+**Steps:**
+1. Router: [INDEX.md](./INDEX.md) → component doc → **Files** section only.
+2. Read [WORKFLOW.md → Procedural sprites](./WORKFLOW.md#procedural-sprites-checklist-r-32).
+3. Grep production scene for `m_Sprite: {fileID: 0}` under the component hierarchy — confirms sprite refresh needed.
+4. Verify controller has: `[ExecuteAlways]`, `EnsureStyle1Layout()`, `RefreshProceduralSprites()`, `ApplyThemeColors()`, `RebuildStyle1Layout()`.
+5. Verify editor Build/menu call `controller.RebuildStyle1Layout()` (not raw `LayoutBuilder` alone).
+6. Tell user: edit **Panel Colors** on the **controller**, not child `Image`/`TMP_Text` objects.
+7. Verify fix in **Scene view without Play** (select object → `OnEnable` refresh).
+8. Update component doc + [CHANGELOG.md](./CHANGELOG.md) if code changed.
+9. **`read_console` (errors only)** — zero errors before handoff (R-33).
+
+**Done when:** rounded Style 1 visuals in Scene view; controller color fields apply live; **console has zero compile errors**.
+
+---
+
+## Composing commands
+
+A typical creation session:
+
+```
+/scan-project query="health bar"
+  → no close match, closest pattern = Card, reusable anims = value-pop, idle-float
+/new-component name=HealthHUD pattern=card style=Style1 data=RhythmHealthSystem
+  → scaffolds, wires, demos
+/register-component name=HealthHUD
+/review-component name=HealthHUD
+  → APPROVED
+```
+
+A typical change session:
+
+```
+/modify-component name=ScoreHUD change="add 'show accuracy' toggle"
+  → adds _showAccuracy bool + code path, updates demo
+/update-index scope=component:ScoreHUD
+/review-component name=ScoreHUD
+```

AI/COMPONENT_INDEX.md

@@ -0,0 +1,60 @@
+# COMPONENT_INDEX  *(thin registry → per-component docs)*
+
+> This file is now a **lightweight registry**. Detailed documentation lives in **one file per component** under [components/](./components/) — the approach that scales best for humans and AI ([components/README.md](./components/README.md)).
+> **Search here, then open exactly one component doc.** Do not scan the codebase ([RULES.md](./RULES.md) R-05). Update here + the component doc + [INDEX.md](./INDEX.md) on any change (R-11).
+>
+> **Live access in Unity (not just docs):** every registered component can also be opened via **`Rhythm → Create <Component> Demo Scene`** (per-component demo scene — see that doc's **Demo** section) **or** on the **UI Component Gallery board** (`Rhythm → Setup UI Component Gallery` / `Rhythm → Create UI Component Gallery Scene`; components with `[UIGalleryComponent]` auto-appear). See [components/README.md → Accessing in Unity](./components/README.md#accessing-a-component-in-unity).
+> Related: [INDEX.md](./INDEX.md) (router) · [PATTERNS.md](./PATTERNS.md) · [ANIMATION_INDEX.md](./ANIMATION_INDEX.md) · [TOKEN_INDEX.md](./TOKEN_INDEX.md)
+
+---
+
+## Components
+
+Each component has a self-contained doc that lists its own files, tokens, animations, and demo. **Open the one you need.**
+
+| Component | Doc (full detail) | Category | Folder | Status | Ver | Tags |
+| --- | --- | --- | --- | --- | --- | --- |
+| Score HUD *(reference / "score meter")* | [components/ScoreHUD.md](./components/ScoreHUD.md) | Component | `Assets/UI/` | Stable | 1.1.0 | score, hud, combo, panel, meter |
+| Main Menu | [components/MainMenu.md](./components/MainMenu.md) | Component | `Assets/UI/Style1/MainMenu/` | Stable | 1.0.0 | menu, navigation, play, songs |
+| Song Carousel | [components/SongCarousel.md](./components/SongCarousel.md) | Component | `Assets/UI/Style1/SongCarousel/` | Stable | 1.0.0 | carousel, songs, selection, scroll |
+| **Title Screen** | [components/TitleScreen.md](./components/TitleScreen.md) | Component | `Assets/Menu/TitleScreen/` | Beta | 0.1.0 | title, menu, 1P, 2P, pushdown-automata |
+| **Song Select** | [components/SongSelect.md](./components/SongSelect.md) | Component | `Assets/Menu/SongSelect/` | Beta | 0.1.0 | song-select, carousel, difficulty, 2P, transition |
+| Style 1 Button *(primitive)* | [components/Style1Button.md](./components/Style1Button.md) | Primitive | `Assets/UI/Style1/` | Stable | 1.0.0 | button, nav, press, hover |
+| UI Component Gallery *(tool / board)* | [components/ComponentGallery.md](./components/ComponentGallery.md) | Tool | `Assets/UI/Style1/ComponentGallery/` | Stable | 1.1.0 | board, gallery, showcase, catalog |
+| Score HUD Bouncy *(variant)* | — | Component | *(removed)* | **Removed** | — | Recreate via [WORKFLOW.md → Creating Variants](./WORKFLOW.md#creating-variants) |
+
+> New component? Copy [components/_TEMPLATE.md](./components/_TEMPLATE.md) → `components/<Name>.md`, then add a row here and in [INDEX.md](./INDEX.md).
+
+---
+
+## Shared design-system classes (Style 1)
+
+Reusable across **all** Style 1 components. **Never duplicate these** (R-10) — reference them. Token values live in [TOKEN_INDEX.md](./TOKEN_INDEX.md).
+
+| Name | Category | File | Used By | Tags |
+| --- | --- | --- | --- | --- |
+| `Style1Palette` | Style (color) | `Assets/UI/Style1/Style1Palette.cs` | Score HUD, demos | color, tokens |
+| `Style1Typography` | Style (type) | `Assets/UI/Style1/Style1Typography.cs` | Score HUD | typography, tmp |
+| `Style1Sprites` | Sprite | `Assets/UI/Style1/Style1Sprites.cs` | Score HUD builder | sprite, procedural |
+| `Style1AsciiImage` (+ shader/mat) | Material/Shader | `Assets/UI/Style1/Style1AsciiImage.cs`, … | Score HUD fill | shader, ascii |
+| `UIEventSystemUtil` | Util | `Assets/UI/UIEventSystemUtil.cs` | Menus, demos | eventsystem, input |
+| `ScoreDisplayUtil` | Util | `Assets/UI/ScoreDisplayUtil.cs` | Score HUD, `RhythmScoreTracker` | util, format |
+| `MarqueeLabel` | UI Primitive (text) | `Assets/Menu/SongSelect/MarqueeLabel.cs` | SongCardView (TitleMarquee, AuthorMarquee, AlbumMarquee) | text, overflow, scroll, marquee |
+
+> **`MarqueeLabel` usage:** `[RequireComponent(RectMask2D)]` — add to a container GO, call `Build()` once, configure typography on `Label`, then call `SetText(string)` to display. Auto-sizes font within `fontSizeMin`/`fontSizeMax`; if text still overflows at the minimum size, ping-pong scrolls horizontally. Edge padding = `space.md` (16 px) each side.
+
+---
+
+## Entry schema (used inside each `components/<Name>.md`)
+
+Every per-component doc carries these fields (see [components/_TEMPLATE.md](./components/_TEMPLATE.md)):
+
+`Name · Category · Folder · Prefab · Pattern · Files · Shared dependencies · Inspector properties · Toggles · Animations · Score/Logic · Editor & menus · Demo · Variants · Used By · Review notes · Version · Author · Last Updated · Tags`
+
+The **Files** section is mandatory and must stay exact — it is what lets an AI agent read only the relevant code instead of the whole project.
+
+---
+
+## Status legend
+
+`Stable` · `Beta` · `Experimental` · `Deprecated` (deprecated rows are kept, never deleted — R-04).