shadok-ai 0.1.209 → 0.1.210

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadok-ai",
-  "version": "0.1.209",
+  "version": "0.1.210",
   "main": "dist/session.js",
   "scripts": {
     "test": "node --import tsx --test test/*.ts .claude/skills/shadok-ai-agents/test/*.test.mjs",

package/public/gauge-dial.js

@@ -0,0 +1,170 @@
+// The 240° quota dial: its CENTRE is the ideal pace and its RIGHT END is
+// exhaustion — see docs/superpowers/specs/2026-07-30-quota-dial-design.md.
+//
+// Loaded as-is by the browser (ESM) and imported by the node/tsx tests, like
+// public/live-text.js, public/notify.js and public/profile-card.js. This module
+// knows nothing about the DOM: it takes numbers and returns numbers, colour
+// strings and SVG path data.
+
+/** Half-sweep, in degrees. 0° is straight up and means "exactly on pace". */
+export const SWEEP_DEG = 120;
+
+/** The viewBox the SVG markup in index.html is drawn against. */
+export const DIAL = { cx: 28, cy: 25, r: 17, w: 56, h: 44 };
+
+/**
+ * The ideal pace is clamped before it becomes the dial's midpoint, because both
+ * ends of a window degenerate otherwise: just after a reset the pace is ~0 and
+ * the left half collapses to a point (the first token spent would slam the
+ * needle to the centre); at the very end of a window it is ~100 and the right
+ * half collapses (any overage would read as "exhausted"). Away from the bands
+ * the clamp costs a sub-degree of accuracy, where accuracy matters — but
+ * *inside* the bands (pace < 2 or > 98) the error is not sub-degree at all: it
+ * can reach 60° (see `dialTitle`'s unclamped `side`, and the two tests that
+ * cover it), because the needle is reading a clamped pace it does not have.
+ * The trade is still the right one there: the pace is too young or too old to
+ * mean much, and the alternative is a needle pinned uselessly at an extreme.
+ *
+ * `PACE_MIN` also has to stay ≤ the pace guardrail's own `PACE_EPSILON`
+ * (`src/pace.ts`, currently both 2) for a property the dial depends on: the
+ * guard blocks a prompt at `used > pace + PACE_EPSILON`, and the dial goes
+ * right-of-centre at `used > clamp(pace, PACE_MIN, PACE_MAX)`. With
+ * `PACE_MIN <= PACE_EPSILON` the dial crosses centre at or before the guard
+ * blocks, so the gauge always warns before a send is refused, never after. Do
+ * not couple the two constants across files for this — just keep it in mind
+ * when either one changes, since nothing enforces it in code.
+ */
+const PACE_MIN = 2;
+const PACE_MAX = 98;
+
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/** Two decimals is plenty for a 56 px viewBox, and keeps the path data short. */
+const round2 = (v) => Math.round(v * 100) / 100;
+
+/**
+ * Position on the dial: -1 nothing consumed, 0 exactly on the ideal pace, +1
+ * quota exhausted.
+ *
+ * The two halves have DIFFERENT scales, deliberately: the pace advances with
+ * the clock, so at 25 % into a window the left half maps used 0→25 % and the
+ * right half maps used 25→100 %. That is what lets one axis answer both "am I
+ * on pace" (the centre) and "is it gone" (the right end).
+ *
+ * `pace` is `idealPacePct` from /usage, NOT `ratioPct`: the latter carries
+ * PACE_EPSILON in its denominator to keep the guardrail from tripping on the
+ * first message after a reset, and baking that fudge in here would offset the
+ * needle from the very tick it is supposed to line up with.
+ */
+export function dialPos(used, pace) {
+  const u = clamp(used, 0, 100);
+  // No reset time → no pace → we still know the consumption honestly, so fall
+  // back to a plain linear 0→100 dial. The caller hides the pace tick.
+  if (pace == null) return u / 50 - 1;
+  const p = clamp(pace, PACE_MIN, PACE_MAX);
+  return clamp(u <= p ? u / p - 1 : (u - p) / (100 - p), -1, 1);
+}
+
+/** Needle angle in degrees, from straight up, clockwise positive. */
+export function dialAngle(used, pace) {
+  return dialPos(used, pace) * SWEEP_DEG;
+}
+
+/**
+ * Colour for a dial position. Amber at the centre, green towards "under pace",
+ * red towards "exhausted" — the same oklab mix the divergent bar used, but keyed
+ * on the dial position so the needle's tint and the arc under it can never
+ * disagree.
+ */
+export function dialColor(pos) {
+  const t = Math.round(clamp(pos, -1, 1) * 100);
+  return t <= 0
+    ? `color-mix(in oklab, var(--amber), var(--ok) ${-t}%)`
+    : `color-mix(in oklab, var(--amber), var(--err) ${t}%)`;
+}
+
+/** A point on the dial's rim, in viewBox units. `deg` is measured like dialAngle. */
+export function dialPoint(deg) {
+  const a = (deg * Math.PI) / 180;
+  return {
+    x: round2(DIAL.cx + DIAL.r * Math.sin(a)),
+    y: round2(DIAL.cy - DIAL.r * Math.cos(a)),
+  };
+}
+
+/**
+ * Angular gap trimmed from each internal end of a segment, so the arc reads as
+ * 24 evenly spaced graduation marks — a deliberate instrument scale, not a
+ * smooth band. Trimmed only between segments: the sweep still spans the full
+ * ±SWEEP_DEG, so the outer marks line up with the needle at its extremes.
+ */
+const GAP_DEG = 0.8;
+
+/**
+ * The gradient arc, as `n` solid segments.
+ *
+ * An SVG gradient cannot follow a path, and a plain horizontal one is
+ * degenerate here: below ±90° the arc curls back inward, so sin(-120°) equals
+ * sin(-60°) and the outer 30° of each side would be painted with the colour of
+ * a completely different reading. Solid segments give a true along-the-sweep
+ * gradient, and the gap between them is the point: 24 flat-coloured marks read
+ * as an instrument scale, not as one smooth band pretending to be a gradient
+ * it structurally cannot render. They are built once and never repainted, so
+ * the extra nodes are free.
+ */
+export function arcSegments(n = 24) {
+  const step = (2 * SWEEP_DEG) / n;
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const a = -SWEEP_DEG + i * step + (i === 0 ? 0 : GAP_DEG / 2);
+    const b = -SWEEP_DEG + (i + 1) * step - (i === n - 1 ? 0 : GAP_DEG / 2);
+    const p1 = dialPoint(a);
+    const p2 = dialPoint(b);
+    out.push({
+      // large-arc-flag 0: every segment is well under 180°. sweep-flag 1:
+      // clockwise on screen, i.e. towards increasing consumption.
+      d: `M ${p1.x} ${p1.y} A ${DIAL.r} ${DIAL.r} 0 0 1 ${p2.x} ${p2.y}`,
+      color: dialColor(-1 + (2 * i + 1) / n),
+    });
+  }
+  return out;
+}
+
+/**
+ * The multi-line tooltip, reused verbatim as the SVG's aria-label. The third
+ * line is what makes the piecewise scale self-explanatory: it states whether
+ * consumption is ahead of, behind, or on the ideal pace.
+ *
+ * `resetText` comes from the caller's fmtReset and is "" when resetsAt is null —
+ * it is filtered out rather than joined, otherwise the tooltip ends on a blank
+ * line.
+ */
+export function dialTitle(label, w, resetText) {
+  const head = `${label} rolling limit`;
+  if (!w) return `${head}\nno data`;
+  const r = Math.round;
+  const used = `${r(w.usedPercentage)}% consumed`;
+  if (w.idealPacePct == null) {
+    return [head, used, "No reset time known, so there is no ideal pace to compare against.", resetText]
+      .filter(Boolean)
+      .join("\n");
+  }
+  // Unclamped on purpose: dialPos clamps the pace to keep the NEEDLE readable at
+  // the edges of a window, but the sentence must state what is actually happening.
+  // Inside the clamp bands the two can disagree — a true sentence beside a clamped
+  // needle beats a false one.
+  const off = w.usedPercentage - w.idealPacePct;
+  const side =
+    off < -0.5
+      ? "Consuming slower than the clock."
+      : off > 0.5
+        ? "Burning faster than the clock."
+        : "Exactly on the ideal pace.";
+  return [
+    head,
+    `${used}, ideal pace ${r(w.idealPacePct)}%, ${r(w.ratioPct)}% of pace`,
+    side,
+    resetText,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/public/index.html

@@ -157,47 +157,48 @@
   @keyframes breathe { 50% { opacity: 0.35; } }
   @media (prefers-reduced-motion: reduce) { .led.busy { animation: none; } }
   header .spacer { flex: 1; }
-  /* Quota gauges (5h / 7d subscription usage).
-     Une barre divergente par fenêtre : le remplissage part du centre
-     (= « au pace », ratio 100 %), vert vers la gauche quand on est SOUS le
-     pace, rouge vers la droite quand on est AU-DESSUS. Position ET couleur
-     portent l'info (accessibilité). */
-  .quota { min-width: 92px; }
-  .quota .meter {
-    position: relative;
-    height: 6px;
-    background: var(--bg-inset);
-    border: 1px solid var(--line);
-    border-radius: 3px;
-    overflow: hidden;
-    margin: 2px 0;
-  }
-  /* Tick central « au pace ». */
-  .quota .meter::before {
-    content: "";
-    position: absolute;
-    left: 50%;
-    top: 0; bottom: 0;
-    width: 1px;
-    margin-left: -0.5px;
-    background: var(--text-dim);
-    opacity: 0.55;
-    z-index: 1;
-  }
-  /* Remplissage : left + width + background-color posés en inline par paintGauge. */
-  .quota .fill {
-    position: absolute;
-    top: 0; bottom: 0;
-    left: 50%;
-    width: 0;
-    background: var(--ok);
-    transition: left 0.4s ease, width 0.4s ease, background-color 0.4s ease;
+  /* Quota dials (5h / 7d subscription usage).
+     A 240° speedometer whose CENTRE is the ideal pace and whose RIGHT END is
+     exhaustion — see docs/superpowers/specs/2026-07-30-quota-dial-design.md.
+     Position AND colour carry the reading, never colour alone. */
+  .quota { min-width: 56px; }
+  .dial { display: block; width: 56px; height: 44px; }
+  /* opacity on the GROUP, not each path: 24 overlapping-alpha strokes would
+     composite twice at every join and brighten the seams instead of hiding
+     them. One group opacity leaves the marks flat and evenly graduated. */
+  .dial .arc { opacity: 0.6; }
+  .dial .arc path { fill: none; stroke-width: 4; }
+  /* No data: the scale stays, as a ghost, so the widget does not vanish. */
+  .dial.nodata .arc { opacity: 0.18; }
+  /* The "on pace" reference, just outside the arc. The needle's tip meets it
+     exactly when the consumption is on pace — they read as one line. */
+  .dial .tick { stroke: var(--text); stroke-width: 1.5; opacity: 0.75; }
+  .dial .needle {
+    stroke: var(--text);
+    stroke-width: 2;
+    stroke-linecap: round;
+    /* Rotated through the CSS transform PROPERTY, not the SVG attribute: only
+       the property transitions reliably. transform-box/-origin put the pivot on
+       the hub in viewBox units. */
+    transform-box: view-box;
+    transform-origin: 28px 25px;
+    transition: transform 0.4s ease;
+  }
+  .dial .pct {
+    font-family: var(--mono);
+    font-size: 12px;
+    font-weight: 600;
+    fill: var(--text);
+    transition: fill 0.4s ease;
   }
-  .quota .qpct {
+  .dial .unit {
     font-family: var(--mono);
-    font-size: 11px;
-    color: var(--text-dim);
-    white-space: nowrap;
+    font-size: 8px;
+    fill: var(--text-dim);
+    letter-spacing: 0.08em;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .dial .needle, .dial .pct { transition: none; }
   }
   button {
     font-family: var(--mono);
@@ -1091,15 +1092,23 @@
 <header>
   <span class="brand">shadok-ai <span class="ver" id="verView" title="running version"></span></span>
   <span class="spacer"></span>
-  <div class="gauge quota" id="quota5h" title="5-hour rolling limit">
-    <span class="label">5h</span>
-    <div class="meter"><span class="fill"></span></div>
-    <span class="qpct">—</span>
+  <div class="gauge quota" id="quota5h" data-window="5h" title="5h rolling limit">
+    <svg class="dial" viewBox="0 0 56 44" role="img" aria-label="5h rolling limit">
+      <g class="arc"></g>
+      <line class="tick" x1="28" y1="5" x2="28" y2="2" visibility="hidden"></line>
+      <line class="needle" x1="28" y1="13" x2="28" y2="5" visibility="hidden"></line>
+      <text class="pct" x="28" y="28" text-anchor="middle">—</text>
+      <text class="unit" x="28" y="41" text-anchor="middle">5h</text>
+    </svg>
   </div>
-  <div class="gauge quota" id="quota7d" title="7-day rolling limit">
-    <span class="label">7d</span>
-    <div class="meter"><span class="fill"></span></div>
-    <span class="qpct">—</span>
+  <div class="gauge quota" id="quota7d" data-window="7d" title="7d rolling limit">
+    <svg class="dial" viewBox="0 0 56 44" role="img" aria-label="7d rolling limit">
+      <g class="arc"></g>
+      <line class="tick" x1="28" y1="5" x2="28" y2="2" visibility="hidden"></line>
+      <line class="needle" x1="28" y1="13" x2="28" y2="5" visibility="hidden"></line>
+      <text class="pct" x="28" y="28" text-anchor="middle">—</text>
+      <text class="unit" x="28" y="41" text-anchor="middle">7d</text>
+    </svg>
   </div>
   <button id="secretsBtn" class="icon" title="Repo secrets (injected as env)">🔑</button>
   <button id="profilesBtn" class="icon" title="Agent profiles (role + guardrails + secrets)">👤</button>
@@ -1405,11 +1414,17 @@
   import { extractLiveText } from "/live-text.js";
   import { profileBlurb, profileBadges } from "/profile-card.js";
   import { notifyState, BLINK_MS } from "/notify.js";
+  import { dialPos, dialColor, arcSegments, dialTitle, SWEEP_DEG } from "/gauge-dial.js";
   window.extractLiveText = extractLiveText;
   window.profileBlurb = profileBlurb;
   window.profileBadges = profileBadges;
   window.notifyState = notifyState;
   window.BLINK_MS = BLINK_MS;
+  window.dialPos = dialPos;
+  window.dialColor = dialColor;
+  window.arcSegments = arcSegments;
+  window.dialTitle = dialTitle;
+  window.SWEEP_DEG = SWEEP_DEG;
 </script>
 <script nonce="__CSP_NONCE__">
   const $ = (id) => document.getElementById(id);
@@ -4202,47 +4217,55 @@
   /** Last verdict from /usage — read by the composer before sending. */
   let paceBlocked = false, paceReason = null;
 
-  /** Couleur du remplissage : dégradé continu vert → ambre → rouge selon le
-   *  ratio usage/pace (0 → 100 → 200). L'ambre entoure le centre « au pace ». */
-  function paceColor(ratio) {
-    if (ratio <= 100) {
-      const t = Math.round(Math.max(0, ratio));            // 0 → vert, 100 → ambre
-      return "color-mix(in oklab, var(--ok), var(--amber) " + t + "%)";
+  /** Paints the static gradient arc of every dial. Runs once: the scale never
+   *  changes, only the needle on top of it does. */
+  function buildDialArcs() {
+    if (!window.arcSegments) return;
+    const NS = "http://www.w3.org/2000/svg";
+    for (const g of document.querySelectorAll(".quota .dial .arc")) {
+      g.replaceChildren(
+        ...window.arcSegments().map(({ d, color }) => {
+          const p = document.createElementNS(NS, "path");
+          p.setAttribute("d", d);
+          // Via the style PROPERTY: color-mix() is not reliably parsed as an
+          // SVG presentation attribute.
+          p.style.stroke = color;
+          return p;
+        }),
+      );
     }
-    const t = Math.round(Math.min(100, ratio - 100));      // 100 → ambre, 200 → rouge
-    return "color-mix(in oklab, var(--amber), var(--err) " + t + "%)";
   }
 
   function paintGauge(el, w) {
-    const fill = el.querySelector(".meter .fill");
-    const pct = el.querySelector(".qpct");
-    const base = el.id === "quota5h" ? "5-hour rolling limit" : "7-day rolling limit";
-    if (!w) {
-      fill.style.width = "0%";
-      fill.style.left = "50%";
-      fill.style.background = "var(--ok)";
-      pct.textContent = "—";
-      el.title = base;
+    const svg = el.querySelector(".dial");
+    const needle = svg.querySelector(".needle");
+    const tick = svg.querySelector(".tick");
+    const pct = svg.querySelector(".pct");
+    const label = el.dataset.window;
+    const title = window.dialTitle
+      ? window.dialTitle(label, w, w ? fmtReset(w.resetsAt) : "")
+      : label + " rolling limit";
+    el.title = title;
+    svg.setAttribute("aria-label", title);
+    svg.classList.toggle("nodata", !w);
+    // Guard on the ESM bridge (invariant 10): this function can be reached
+    // before the module has run. Degrade to the number rather than paint a
+    // needle at a wrong angle.
+    if (!w || !window.dialPos) {
+      needle.setAttribute("visibility", "hidden");
+      tick.setAttribute("visibility", "hidden");
+      pct.textContent = w ? Math.round(w.usedPercentage) + "%" : "—";
+      pct.style.fill = "var(--text-dim)";
       return;
     }
-    const used = Math.round(w.usedPercentage);
-    const pace = w.idealPacePct == null ? null : Math.round(w.idealPacePct);
-    const ratio = w.ratioPct == null ? null : Math.round(w.ratioPct);
-    // Sans ratio (pas de pace calculable), on centre : barre vide + tick seul.
-    const r = ratio == null ? 100 : ratio;
-    // Ratio → position [-1, +1] ; 50 % (centre) = au pace (ratio 100).
-    const pos = Math.max(-1, Math.min(1, (r - 100) / 100));
-    const half = Math.abs(pos) * 50;                       // % de la demi-largeur
-    fill.style.left = (pos < 0 ? 50 - half : 50) + "%";
-    fill.style.width = half + "%";
-    fill.style.background = paceColor(r);
-    pct.textContent = used + "%";
-    // fmtReset returns "" when resetsAt is null — the separator goes with it,
-    // otherwise the tooltip ends on a dangling " · ".
-    const reset = fmtReset(w.resetsAt);
-    el.title = base + " — " + used + "% used"
-      + (pace === null ? "" : ", ideal pace " + pace + "% (" + ratio + "% of pace)")
-      + (reset ? " · " + reset : "");
+    const pos = window.dialPos(w.usedPercentage, w.idealPacePct);
+    needle.setAttribute("visibility", "visible");
+    needle.style.transform = "rotate(" + (pos * window.SWEEP_DEG).toFixed(1) + "deg)";
+    // Without a reset time there is no ideal pace, so there is nothing for the
+    // tick to mark — drawing it would assert a reference we do not have.
+    tick.setAttribute("visibility", w.idealPacePct == null ? "hidden" : "visible");
+    pct.textContent = Math.round(w.usedPercentage) + "%";
+    pct.style.fill = window.dialColor(pos);
   }
 
   async function refreshUsage() {
@@ -4261,7 +4284,12 @@
       paceReason = null;
     }
   }
-  refreshUsage();
+  // The ESM bridge (window.dialPos & co) runs AFTER this classic script — see
+  // invariant 10 in CLAUDE.md. Painting now would leave blank dials in silence.
+  document.addEventListener("DOMContentLoaded", () => {
+    buildDialArcs();
+    refreshUsage();
+  });
   setInterval(refreshUsage, 60_000);
 
   // On load: restore the remembered groups (server-side, keyed by launch