Add star-based scalar rating controls

Author: apartsin

app/frontend/static/app.js

@@ -125,6 +125,33 @@ function collectRatings() {
   })).filter((entry) => entry.rating > 0);
 }
 
+function ratingCaption(value) {
+  if (!value) {
+    return "No rating selected yet";
+  }
+  if (value === 1) return "1 star selected";
+  return `${value} stars selected`;
+}
+
+function applyStarRating(candidateId, value) {
+  const numericValue = Number(value || 0);
+  const hiddenInput = document.querySelector(`.rating-input[data-candidate-id="${candidateId}"]`);
+  if (hiddenInput) {
+    hiddenInput.value = String(numericValue);
+  }
+  const buttons = Array.from(document.querySelectorAll(`.star-button[data-candidate-id="${candidateId}"]`));
+  buttons.forEach((button) => {
+    const buttonValue = Number(button.dataset.ratingValue || 0);
+    const active = numericValue > 0 && buttonValue <= numericValue;
+    button.classList.toggle("active", active);
+    button.setAttribute("aria-pressed", active ? "true" : "false");
+  });
+  const caption = document.querySelector(`.star-rating-caption[data-candidate-id="${candidateId}"]`);
+  if (caption) {
+    caption.textContent = ratingCaption(numericValue);
+  }
+}
+
 function buildFeedbackPayload(feedbackMode) {
   if (feedbackMode === "pairwise") {
     const winner = document.querySelector(".pairwise-winner-input:checked")?.dataset.candidateId;
@@ -285,7 +312,7 @@ if (nextRoundButton) {
       await pollJob(job.status_url, {
         onProgress: (snapshot) => {
           setStatus(snapshot.status_message);
-          setProgress(snapshot.progress, "Generating next round");
+      setProgress(snapshot.progress, snapshot.status_message || "Generating next round");
         },
       });
       setStatus("Round generated. Refreshing session view...");
@@ -299,6 +326,16 @@ if (nextRoundButton) {
   });
 }
 
+Array.from(document.querySelectorAll(".star-button")).forEach((button) => {
+  button.addEventListener("click", () => {
+    if (button.disabled) return;
+    const candidateId = button.dataset.candidateId;
+    const value = Number(button.dataset.ratingValue || 0);
+    applyStarRating(candidateId, value);
+    traceFrontend("feedback.rating.selected", { candidate_id: candidateId, rating: value });
+  });
+});
+
 const submitFeedbackButton = document.getElementById("submit-feedback-button");
 if (submitFeedbackButton) {
   traceFrontend("round.visible", { round_id: submitFeedbackButton.dataset.roundId });
@@ -321,7 +358,7 @@ if (submitFeedbackButton) {
       await pollJob(job.status_url, {
         onProgress: (snapshot) => {
           setStatus(snapshot.status_message);
-          setProgress(snapshot.progress, "Applying feedback");
+      setProgress(snapshot.progress, snapshot.status_message || "Applying feedback");
         },
       });
       setStatus("Feedback submitted. Refreshing session view...");

app/frontend/static/styles.css

@@ -89,6 +89,52 @@ textarea { min-height: 100px; resize: vertical; }
   gap: 8px;
   margin-top: 10px;
 }
+.rating-widget {
+  display: grid;
+  gap: 8px;
+}
+.rating-label {
+  font-weight: 600;
+}
+.star-rating {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+.star-button {
+  width: 40px;
+  height: 40px;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  background: #fff8ef;
+  color: #c7b49b;
+  font-size: 1.3rem;
+  line-height: 1;
+  cursor: pointer;
+  transition: transform 120ms ease, background 120ms ease, color 120ms ease, border-color 120ms ease;
+}
+.star-button:hover:not(:disabled),
+.star-button:focus-visible:not(:disabled) {
+  transform: translateY(-1px);
+  border-color: var(--accent-2);
+  color: var(--accent-2);
+  outline: none;
+}
+.star-button.active {
+  background: linear-gradient(180deg, #fff4cc, #ffd98a);
+  border-color: #d28d2f;
+  color: #9a5700;
+}
+.star-button:disabled {
+  cursor: default;
+  opacity: 0.75;
+}
+.star-rating-caption {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.92rem;
+}
 .choice-row {
   display: flex;
   align-items: center;
@@ -165,4 +211,8 @@ code { background: #f2ebdf; padding: 2px 6px; border-radius: 8px; }
 @media (max-width: 700px) {
   .page { padding: 20px 14px 32px; }
   .section-head { display: block; }
+  .star-button {
+    width: 36px;
+    height: 36px;
+  }
 }

app/frontend/templates/session.html

@@ -59,9 +59,24 @@ <h3>{{ candidate.id }}</h3>
                 <p>z: {{ candidate.z }}</p>
                 <div class="candidate-controls" data-feedback-mode="{{ session.config.feedback_mode }}">
                   {% if session.config.feedback_mode == "scalar_rating" %}
-                    <label>Rating
-                      <input type="number" min="1" max="5" class="rating-input" data-candidate-id="{{ candidate.id }}" inputmode="numeric" {% if current_round.feedback_events %}disabled{% endif %}>
-                    </label>
+                    <div class="rating-widget" data-candidate-id="{{ candidate.id }}">
+                      <span class="rating-label">Rating</span>
+                      <div class="star-rating" role="radiogroup" aria-label="Rate candidate {{ candidate.id }}">
+                        {% for star in [1, 2, 3, 4, 5] %}
+                          <button
+                            type="button"
+                            class="star-button"
+                            data-candidate-id="{{ candidate.id }}"
+                            data-rating-value="{{ star }}"
+                            aria-label="{{ star }} star{% if star > 1 %}s{% endif %}"
+                            aria-pressed="false"
+                            {% if current_round.feedback_events %}disabled{% endif %}
+                          >★</button>
+                        {% endfor %}
+                      </div>
+                      <input type="hidden" class="rating-input" data-candidate-id="{{ candidate.id }}" value="0">
+                      <p class="star-rating-caption" data-candidate-id="{{ candidate.id }}">No rating selected yet</p>
+                    </div>
                   {% elif session.config.feedback_mode == "pairwise" %}
                     <label class="choice-row">
                       <input type="radio" name="pairwise_winner" class="pairwise-winner-input" data-candidate-id="{{ candidate.id }}" {% if current_round.feedback_events %}disabled{% endif %}>
@@ -97,7 +112,7 @@ <h3>{{ candidate.id }}</h3>
           {% if not current_round.feedback_events %}
             <p class="hint">
               {% if session.config.feedback_mode == "scalar_rating" %}
-                Rate one or more candidates from 1 to 5. The highest-rated candidate becomes the winner.
+                Click one to five stars on any candidates you want to rate. Higher stars mean stronger preference.
               {% elif session.config.feedback_mode == "pairwise" %}
                 Choose one winner and one loser.
               {% elif session.config.feedback_mode == "winner_only" %}

docs/developer_guide.md

@@ -239,6 +239,11 @@ During round generation and feedback submission:
 
 This keeps the UI responsive while the real GPU-backed backend works in the background.
 
+Current progress phrases are intentionally operation-specific. For example:
+
+- round generation reports phases such as `Checking session readiness`, `Sampling 5 candidate directions`, `Rendering candidate images on the model backend`, and `Refreshing trace report and replay data`
+- feedback submission reports phases such as `Normalizing and validating user preferences`, `Updating the steering model from your feedback`, and `Feedback applied and next round unlocked`
+
 ![Session lifecycle diagram](./assets/illustrations/session_lifecycle.svg)
 
 ## 6. Core Extension Points
@@ -301,7 +306,7 @@ The current API quality contract is:
 
 The current feedback-mode contract is:
 
-- `scalar_rating` uses explicit rating inputs
+- `scalar_rating` uses explicit clickable star ratings
 - `pairwise` uses explicit winner and loser selection controls
 - `winner_only` uses an explicit winner selection control
 - `approve_reject` uses explicit approval checkboxes plus winner selection

docs/user_guide.md

@@ -89,6 +89,15 @@ When you generate a round or submit feedback, the session page shows:
 - a status label such as queueing, running, completed, or failed
 - inline error text if something goes wrong
 
+The status text is phase-aware. You may see messages such as:
+
+- `Checking session readiness`
+- `Sampling 5 candidate directions`
+- `Rendering candidate images on the model backend`
+- `Normalizing and validating user preferences`
+- `Updating the steering model from your feedback`
+- `Refreshing trace report and replay data`
+
 While work is running:
 
 - the relevant button is disabled
@@ -110,7 +119,7 @@ Each card shows:
 
 The visible controls change with the selected feedback mode:
 
-- `scalar_rating` shows rating inputs
+- `scalar_rating` shows clickable one-to-five star controls
 - `pairwise` shows explicit winner and loser choices
 - `winner_only` shows a single winner choice
 - `approve_reject` shows approval choices plus a preferred approved winner

site/docs/developer_guide.html

@@ -221,6 +221,11 @@ <h2 id="52-progress-behavior">5.2 Progress Behavior</h2>
 <li>impossible async requests are rejected before queueing when the session or round is already in a conflicting state</li>
 </ul>
 <p>This keeps the UI responsive while the real GPU-backed backend works in the background.</p>
+<p>Current progress phrases are intentionally operation-specific. For example:</p>
+<ul>
+<li>round generation reports phases such as <code>Checking session readiness</code>, <code>Sampling 5 candidate directions</code>, <code>Rendering candidate images on the model backend</code>, and <code>Refreshing trace report and replay data</code></li>
+<li>feedback submission reports phases such as <code>Normalizing and validating user preferences</code>, <code>Updating the steering model from your feedback</code>, and <code>Feedback applied and next round unlocked</code></li>
+</ul>
 <p><img alt="Session lifecycle diagram" src="assets/illustrations/session_lifecycle.svg"></p>
 <h2 id="6-core-extension-points">6. Core Extension Points</h2>
 <h3 id="61-add-a-sampler">6.1 Add a sampler</h3>
@@ -274,7 +279,7 @@ <h3 id="63-evolve-generation">6.3 Evolve generation</h3>
 </ul>
 <p>The current feedback-mode contract is:</p>
 <ul>
-<li><code>scalar_rating</code> uses explicit rating inputs</li>
+<li><code>scalar_rating</code> uses explicit clickable star ratings</li>
 <li><code>pairwise</code> uses explicit winner and loser selection controls</li>
 <li><code>winner_only</code> uses an explicit winner selection control</li>
 <li><code>approve_reject</code> uses explicit approval checkboxes plus winner selection</li>

site/docs/user_guide.html

@@ -94,6 +94,15 @@ <h2 id="41-progress-and-status">4.1 Progress and Status</h2>
 <li>a status label such as queueing, running, completed, or failed</li>
 <li>inline error text if something goes wrong</li>
 </ul>
+<p>The status text is phase-aware. You may see messages such as:</p>
+<ul>
+<li><code>Checking session readiness</code></li>
+<li><code>Sampling 5 candidate directions</code></li>
+<li><code>Rendering candidate images on the model backend</code></li>
+<li><code>Normalizing and validating user preferences</code></li>
+<li><code>Updating the steering model from your feedback</code></li>
+<li><code>Refreshing trace report and replay data</code></li>
+</ul>
 <p>While work is running:</p>
 <ul>
 <li>the relevant button is disabled</li>
@@ -113,7 +122,7 @@ <h2 id="5-understanding-the-candidate-cards">5. Understanding the Candidate Card
 </ul>
 <p>The visible controls change with the selected feedback mode:</p>
 <ul>
-<li><code>scalar_rating</code> shows rating inputs</li>
+<li><code>scalar_rating</code> shows clickable one-to-five star controls</li>
 <li><code>pairwise</code> shows explicit winner and loser choices</li>
 <li><code>winner_only</code> shows a single winner choice</li>
 <li><code>approve_reject</code> shows approval choices plus a preferred approved winner</li>

tests/e2e/app.spec.js

@@ -41,12 +41,10 @@ test.describe("StableSteering browser flow", () => {
     await expect(page.locator(".image-card")).toHaveCount(5);
     await expect(page.locator(".image-card img").first()).toBeVisible();
 
-    const ratings = page.locator(".rating-input");
-    await ratings.nth(0).fill("2");
-    await ratings.nth(1).fill("5");
-    await ratings.nth(2).fill("4");
-    await ratings.nth(3).fill("3");
-    await ratings.nth(4).fill("1");
+    await page.locator('.star-button[data-candidate-id]').nth(1 * 5 + 4).click();
+    await page.locator('.star-button[data-candidate-id]').nth(2 * 5 + 3).click();
+    await page.locator('.star-button[data-candidate-id]').nth(3 * 5 + 2).click();
+    await page.locator('.star-button[data-candidate-id]').nth(4 * 5 + 0).click();
     await page.getByRole("button", { name: "Submit feedback" }).click();
 
     await expect(page.getByText("Status:")).toBeVisible();
@@ -70,12 +68,10 @@ test.describe("StableSteering browser flow", () => {
     await page.getByRole("button", { name: "Generate next round" }).click();
     await expect(page.getByRole("heading", { name: /Round 1/ })).toBeVisible();
 
-    const ratings = page.locator(".rating-input");
-    await ratings.nth(0).fill("1");
-    await ratings.nth(1).fill("4");
-    await ratings.nth(2).fill("5");
-    await ratings.nth(3).fill("3");
-    await ratings.nth(4).fill("2");
+    await page.locator('.star-button[data-candidate-id]').nth(1 * 5 + 3).click();
+    await page.locator('.star-button[data-candidate-id]').nth(2 * 5 + 4).click();
+    await page.locator('.star-button[data-candidate-id]').nth(3 * 5 + 2).click();
+    await page.locator('.star-button[data-candidate-id]').nth(4 * 5 + 1).click();
     await page.getByRole("button", { name: "Submit feedback" }).click();
     await expect(page.getByText("Status:")).toBeVisible();
     await expect(page.getByRole("link", { name: "Open replay" })).toBeVisible();