docs(openspec): propose polish-plugin-messages

openspec/changes/polish-plugin-messages/design.md

@@ -0,0 +1,38 @@
+# Design
+
+## Context
+
+All player-facing texts are MiniMessage templates in `lang/messages_en.properties` and `lang/messages_de.properties`,
+rendered by `i18n/Messages`, which chooses German for a `de` client locale and English otherwise. Placeholders are
+filled as unparsed text, so player names can never inject formatting.
+
+## Decisions
+
+### 1. Palette as MiniMessage tags in the bundles
+
+Colours stay in the templates (no Java constants), so translations and operator overrides can restyle them. The
+palette: brand gradient `#7c3aed → #db2777` (prefix, headers), commands `#c4b5fd`, arguments `#a78bfa`, text
+`gray`, separators `dark_gray` (`»`, `•`), success `#86efac`, errors `#fca5a5`, hints `#fde68a`, leader `gold` with
+`★`. A short colour guide at the top of the English bundle documents it.
+
+### 2. Clickable help
+
+Each help line uses `<click:suggest_command:'/party invite '>` and `<hover:show_text:'…'>`; the hover text is its own
+key (`command.help.<name>.hover`), so it is translated with the rest. The help title gets a separator line.
+
+### 3. Locale resolution and overrides
+
+Bundles are looked up as `language_COUNTRY`, then `language`, then `en`. Built-in bundles come from the classpath;
+files named `messages_<tag>.properties` in `plugins/quelea/lang/` (read once at start-up) are merged key by key over
+the built-in bundle of the same tag or form a new language. A key missing in the chosen bundle falls back to the
+English key, so a partial translation never shows a raw key.
+
+Rejected: Adventure's `GlobalTranslator` with `TranslatableComponent` (it renders on the server per viewer, but
+MiniMessage placeholders and click events in translations need a custom translator anyway, and the existing
+per-locale rendering already does the job); hot reload of override files (a proxy restart is the normal way to apply
+template changes).
+
+## Risks / Trade-offs
+
+- Operators can break a message with invalid MiniMessage in an override; the plugin logs the key and falls back to
+  the built-in English text instead of sending nothing.

openspec/changes/polish-plugin-messages/proposal.md

@@ -0,0 +1,47 @@
+# Proposal
+
+**Ships as:** `feat(velocity)`: one code pull request `feat(velocity): give party messages colour, clickable help and open translations`.
+
+## Why
+
+The first test on the team proxy showed that the party messages work but look flat: the help is a grey wall of
+text, commands cannot be clicked, and success, failure and hints look alike. Players should see at a glance what
+happened and be able to click a command instead of typing it.
+
+Translations are fixed to English and German inside the jar. Adding a language or adjusting a colour needs a new
+release, although the texts are plain MiniMessage templates that operators could adapt in the proxy template.
+
+## What Changes
+
+- **A consistent palette** across all messages: the existing violet-to-pink brand gradient for headers and the
+  prefix, light violet for commands, grey for explanations, green for success, red for errors, amber for hints,
+  gold with a star for the leader.
+- **Clickable help:** every line of `/party` help suggests its command on click and explains it on hover; arguments
+  are shown in a second colour.
+- **Richer feedback:** invites with hover texts on [Accept] and [Deny], the member list with leader marker and
+  online hint, the party chat with its own prefix and a coloured sender name.
+- **One message per outcome:** today the actor reads both the command answer and the event ("Party created" plus
+  "X created the party", "You joined the party" twice). The actor gets the command answer only; a second click on an
+  old [Accept] says "already in this party".
+- **Open translations:** the plugin picks the bundle for the client locale (`de_DE` → `de` → `en`) from any
+  `messages_<language>.properties` it ships or finds in `plugins/quelea/lang/`; a file there overrides single keys of
+  the built-in bundle, missing keys fall back to English. Operators can add a language or recolour a message
+  without a release.
+
+## Capabilities
+
+### New Capabilities
+None.
+
+### Modified Capabilities
+- `velocity-plugin`: message presentation and translations.
+
+## Out of Scope
+
+- Redirecting normal chat into the party chat with a prefix (`@`) or a toggle. It needs SignedVelocity on the
+  proxies and a Minestom implementation of its backend part, and comes as its own change.
+- New languages beyond English and German in the jar.
+
+## Impact
+
+- Plugin only: message bundles, the `Messages` loader, command help and event handler rendering, tests.

openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md

@@ -0,0 +1,49 @@
+# Spec Delta
+
+## Purpose
+The proxy side: commands, messages, presence reporting and the event consumer.
+
+## ADDED Requirements
+
+### Requirement: Clickable help
+The plugin SHALL render every `/party` help line so that clicking it suggests the command in the chat input and hovering explains it in the player's language.
+
+#### Scenario: Click on invite
+- **WHEN** a player clicks the help line of `/party invite`
+- **THEN** their chat input contains `/party invite `
+
+### Requirement: Message palette
+The plugin SHALL colour messages by meaning: the brand gradient for the prefix and headers, green for successful actions, red for errors and problems, amber for hints, and gold with a star for the party leader.
+
+#### Scenario: Problem shown in red
+- **WHEN** a command fails with `party-full`
+- **THEN** the player reads the translated problem text in red after the party prefix
+
+### Requirement: Translations from bundles and overrides
+The plugin SHALL choose the message bundle for the client locale by language and country, then language, then English, SHALL merge `messages_<tag>.properties` files from `plugins/quelea/lang/` over the built-in bundles key by key, and SHALL fall back to the English text for any key missing in the chosen bundle or whose template cannot be parsed.
+
+#### Scenario: Operator adds French
+- **GIVEN** `plugins/quelea/lang/messages_fr.properties` translates only `party.joined`
+- **WHEN** a player with locale `fr_FR` sees a join and a disband
+- **THEN** the join is French and the disband is English
+
+#### Scenario: Override recolours a message
+- **GIVEN** `plugins/quelea/lang/messages_de.properties` overrides `prefix`
+- **WHEN** a German player receives any message
+- **THEN** it starts with the overridden prefix and the other texts are the built-in German ones
+
+### Requirement: One message per outcome
+The plugin SHALL tell the player who ran a command about its outcome exactly once: the command's own answer goes to the actor, and the matching party event SHALL NOT notify the actor again; other members are notified by the event only.
+
+#### Scenario: Create
+- **WHEN** a player creates a party
+- **THEN** they read one confirmation with the invite hint and no second "created the party" line
+
+#### Scenario: Accept
+- **WHEN** a player accepts an invite
+- **THEN** they read "You joined the party." once, and the other members read that the player joined
+
+#### Scenario: Accept again
+- **GIVEN** a player already joined the party that invited them
+- **WHEN** they click the old [Accept] button again
+- **THEN** they read that they are already in that party instead of "no pending invites"

openspec/changes/polish-plugin-messages/tasks.md

@@ -0,0 +1,29 @@
+# Tasks
+
+## 1. Translations
+
+- [ ] 1.1 `Messages`: locale resolution `language_COUNTRY` → `language` → `en`, per-key fallback to English, override
+      directory `plugins/quelea/lang/` merged over built-in bundles, invalid templates fall back with one log line.
+- [ ] 1.2 Tests with a `@TempDir` override directory (new language, partial override, broken template).
+
+## 2. Presentation
+
+- [ ] 2.1 Palette applied to all keys in `messages_en.properties` and `messages_de.properties`, with a colour guide
+      comment.
+- [ ] 2.2 Clickable and hoverable help lines (`command.help.<name>.hover` keys).
+- [ ] 2.3 Invite buttons with hover, member list with leader star, party chat format.
+- [ ] 2.4 Bundle tests: every bundle has the English key set, every template parses, help lines carry click events.
+
+## 3. Duplicates
+
+- [ ] 3.1 The actor of `create`, `accept`, `deny`, `leave`, `kick`, `promote`, `disband` gets only the command answer;
+      event notifications skip the actor (handler tests with fakes).
+- [ ] 3.2 A repeated accept for the party the player is already in answers "already in this party".
+
+## 4. Documentation
+
+- [ ] 4.1 README: how to add a language or override a message in the proxy template.
+
+## 5. Pull request
+
+- [ ] 5.1 Open the code pull request `feat(velocity): give party messages colour, clickable help and open translations`.