@worca/ui 0.40.0 → 0.41.0

package/app/styles.css

@@ -155,15 +155,50 @@ h1, h2, h3, h4, h5, h6 {
 }
 
 .sidebar.collapsed .sidebar-section-header,
-.sidebar.collapsed .sidebar-item span,
+/* `.sidebar-item-left > span` targets only label spans — the outer
+   `.sidebar-item-left` is itself a span and would have been swept up
+   by the broader `.sidebar-item span` selector, hiding the icon too. */
+.sidebar.collapsed .sidebar-item-left > span,
 .sidebar.collapsed .conn-label,
-.sidebar.collapsed .logo-text {
+.sidebar.collapsed .logo-text,
+.sidebar.collapsed .sidebar-project-section,
+.sidebar.collapsed .sidebar-new-run-chevron-dropdown {
   display: none;
 }
 
+/* In the collapsed rail, nav items become icon-only — center them so they
+   sit under the toggle button rather than floating against the left edge. */
+.sidebar.collapsed .sidebar-item {
+  justify-content: center;
+  margin: 2px 6px;
+  padding: 8px 6px;
+}
+.sidebar.collapsed .sidebar-item-left {
+  gap: 0;
+}
+.sidebar.collapsed .sidebar-new-run {
+  padding: 4px 6px;
+}
+.sidebar.collapsed .sidebar-new-run-split {
+  width: auto;
+}
+.sidebar.collapsed .sidebar-footer {
+  justify-content: center;
+  padding: 12px 6px;
+}
+
 .sidebar-logo {
-  padding: 20px 16px 12px;
+  padding: 16px 12px 12px 16px;
   border-bottom: 1px solid var(--border-subtle);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.sidebar.collapsed .sidebar-logo {
+  justify-content: center;
+  padding: 16px 6px 12px;
 }
 
 .logo-text {
@@ -174,6 +209,35 @@ h1, h2, h3, h4, h5, h6 {
   color: var(--fg);
 }
 
+.sidebar-toggle-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--radius);
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+  flex-shrink: 0;
+  transition:
+    background var(--transition-fast),
+    color var(--transition-fast),
+    border-color var(--transition-fast);
+}
+
+.sidebar-toggle-btn:hover {
+  background: var(--border);
+  color: var(--fg);
+}
+
+.sidebar-toggle-btn:focus-visible {
+  outline: none;
+  border-color: var(--accent);
+}
+
 /* --- 6. Sidebar Sections --- */
 .sidebar-section {
   padding: 8px 0;
@@ -410,11 +474,548 @@ h1, h2, h3, h4, h5, h6 {
   color: #ffffff;
 }
 
+.action-btn--ghost {
+  border-color: transparent;
+  color: var(--text-muted);
+}
+
+.action-btn--ghost:hover {
+  border-color: var(--border);
+  color: var(--text);
+}
+
 .action-btn:disabled {
   opacity: 0.6;
   cursor: not-allowed;
 }
 
+.run-stage-actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 6px;
+  padding: 0 0 4px;
+  flex-wrap: wrap;
+}
+
+/* --- Run Timeline ---
+   Local tokens layered on the global palette. --text-strong gives a
+   WCAG-AA-safe muted color for labels (4.5:1 on white at 12-13px), avoiding
+   the very pale --muted (#94a3b8). All other colors route through brand vars
+   so dark mode and theme tweaks land for free. */
+.run-timeline {
+  --tl-text-strong: #475569;
+  --tl-row-alt-bg: rgba(15, 23, 42, 0.04);
+  --tl-row-divider: rgba(15, 23, 42, 0.08);
+  --tl-grid-line: rgba(15, 23, 42, 0.05);
+  --tl-axis-line: rgba(15, 23, 42, 0.18);
+  --tl-axis-tick: rgba(15, 23, 42, 0.28);
+  --tl-axis-label: rgba(15, 23, 42, 0.62);
+  --tl-row-label: rgba(15, 23, 42, 0.78);
+  --tl-row-label-count: rgba(15, 23, 42, 0.45);
+  --tl-loopback-default-opacity: 0.7;
+  --tl-loopback-hint: rgba(15, 23, 42, 0.4);
+  --tl-bar-stroke: rgba(15, 23, 42, 0.22);
+  --tl-bar-shadow: rgba(15, 23, 42, 0.22);
+  --timeline-gap-fill: rgba(15, 23, 42, 0.04);
+  --timeline-gap-dot: rgba(15, 23, 42, 0.32);
+
+  padding: 16px 20px 24px;
+  background: var(--bg, #fff);
+  border: 1px solid var(--border-subtle, rgba(226, 232, 240, 0.6));
+  border-radius: 10px;
+  overflow-x: auto;
+  position: relative;
+}
+
+/* worca-ui drives dark mode via [data-theme="dark"] on the html element,
+   not via prefers-color-scheme. Both selectors here so the timeline tokens
+   flip with the rest of the chrome. */
+[data-theme="dark"] .run-timeline,
+.run-timeline[data-theme="dark"] {
+  --tl-text-strong: #cbd5e1;
+  --tl-row-alt-bg: rgba(255, 255, 255, 0.04);
+  --tl-row-divider: rgba(255, 255, 255, 0.1);
+  --tl-grid-line: rgba(255, 255, 255, 0.07);
+  --tl-axis-line: rgba(255, 255, 255, 0.22);
+  --tl-axis-tick: rgba(255, 255, 255, 0.35);
+  --tl-axis-label: rgba(255, 255, 255, 0.7);
+  --tl-row-label: rgba(255, 255, 255, 0.9);
+  --tl-row-label-count: rgba(255, 255, 255, 0.55);
+  --tl-loopback-hint: rgba(255, 255, 255, 0.5);
+  --tl-bar-stroke: rgba(255, 255, 255, 0.32);
+  --tl-bar-shadow: rgba(0, 0, 0, 0.45);
+  --timeline-gap-fill: rgba(255, 255, 255, 0.06);
+  --timeline-gap-dot: rgba(255, 255, 255, 0.4);
+}
+
+/* Top stats summary */
+.timeline-summary {
+  display: flex;
+  align-items: center;
+  gap: 28px;
+  /* Right-padding reserves space for the absolutely-positioned .timeline-toolbar
+     anchored at top:16px / right:20px so the stats never run under the buttons. */
+  padding: 4px 260px 16px 0;
+  flex-wrap: wrap;
+}
+.summary-stat {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 64px;
+}
+.summary-stat-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--tl-text-strong);
+  font-weight: 500;
+}
+.summary-stat-value {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--fg, #0f172a);
+  font-variant-numeric: tabular-nums;
+}
+.summary-spacer {
+  flex: 1;
+}
+
+/* Toolbar — anchored to the top-right corner of the timeline box.
+   Stacks the zoom button group above the keyboard-hint text, both right-aligned. */
+.timeline-toolbar {
+  position: absolute;
+  top: 16px;
+  right: 20px;
+  z-index: 2;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 6px;
+}
+.timeline-toolbar-group {
+  display: inline-flex;
+  border: 1px solid var(--border, #e2e8f0);
+  border-radius: 6px;
+  overflow: hidden;
+  background: var(--bg, #fff);
+}
+.timeline-zoom-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 30px;
+  height: 28px;
+  padding: 0 8px;
+  border: none;
+  background: transparent;
+  color: var(--tl-text-strong);
+  cursor: pointer;
+  user-select: none;
+  border-right: 1px solid var(--border, #e2e8f0);
+}
+.timeline-zoom-btn:last-child {
+  border-right: none;
+}
+.timeline-zoom-btn:hover {
+  background: var(--bg-secondary, #f8fafc);
+  color: var(--fg, #0f172a);
+}
+.timeline-zoom-btn:active {
+  background: var(--bg-tertiary, #f1f5f9);
+}
+.timeline-zoom-btn:focus-visible {
+  outline: 2px solid var(--accent, #3b82f6);
+  outline-offset: -2px;
+  z-index: 1;
+}
+.timeline-toolbar-hint {
+  font-size: 11px;
+  color: var(--tl-text-strong);
+  text-align: right;
+}
+
+/* SVG wrapper */
+.timeline-svg-wrap {
+  position: relative;
+  overflow: visible;
+}
+
+/* Row backgrounds */
+.row-bg-alt {
+  fill: var(--tl-row-alt-bg);
+}
+.row-divider {
+  stroke: var(--tl-row-divider);
+  stroke-width: 1;
+  shape-rendering: crispEdges;
+}
+.grid-line {
+  stroke: var(--tl-grid-line);
+  stroke-width: 1;
+  shape-rendering: crispEdges;
+}
+
+/* Row labels — match the uppercase tracking used by .pipeline-stage-name so
+   timeline rows read like the stage section headers elsewhere in the UI. */
+.row-label {
+  font-size: 12px;
+  font-weight: 600;
+  fill: var(--tl-row-label);
+  font-family: var(--sl-font-sans, system-ui, sans-serif);
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+.row-label-count {
+  font-size: 11px;
+  font-weight: 500;
+  fill: var(--tl-row-label-count);
+  text-transform: none;
+  letter-spacing: 0;
+}
+.loopback-hint {
+  font-size: 10px;
+  fill: var(--tl-loopback-hint);
+  pointer-events: none;
+}
+
+/* Bars
+   Default: thin contrasting hairline stroke so bar edges read clearly without
+   any per-bar divider. Hover/active: lift via translateY + drop-shadow so the
+   bar "raises" off the chart. Active state persists while the iteration drawer
+   is open (driven by the .is-active class). Reduced-motion drops the lift. */
+.timeline-bar {
+  cursor: pointer;
+  stroke: var(--tl-bar-stroke);
+  stroke-width: 1;
+  transition:
+    filter 130ms ease,
+    transform 130ms ease,
+    stroke-width 130ms ease;
+  /* SVG rect transforms relative to the SVG viewport origin, not the rect
+     itself — fine for translateY since we want a small vertical lift. */
+}
+.timeline-bar:hover,
+.timeline-bar.is-active {
+  filter: drop-shadow(0 3px 6px var(--tl-bar-shadow));
+  transform: translateY(-1px);
+  stroke-width: 1.25;
+}
+.timeline-bar:focus-visible {
+  /* Subtle keyboard-focus indicator — no bold ring. The raised+shadow state
+     above also kicks in on focus via :focus-visible :is() below. */
+  outline: 1.5px dashed var(--accent, #3b82f6);
+  outline-offset: 2px;
+}
+.timeline-bar:focus-visible {
+  filter: drop-shadow(0 3px 6px var(--tl-bar-shadow));
+  transform: translateY(-1px);
+}
+@media (prefers-reduced-motion: reduce) {
+  .timeline-bar,
+  .timeline-bar:hover,
+  .timeline-bar.is-active,
+  .timeline-bar:focus-visible {
+    transform: none;
+  }
+}
+.bar-label {
+  font-size: 10px;
+  font-weight: 600;
+  fill: #fff;
+  font-family: var(--sl-font-sans, system-ui, sans-serif);
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.02em;
+}
+
+/* Gaps */
+.timeline-gap {
+  cursor: default;
+}
+.timeline-gap:focus-visible {
+  outline: 2px solid var(--accent, #3b82f6);
+  outline-offset: 1px;
+}
+.gap-bg {
+  fill: var(--timeline-gap-fill);
+}
+.gap-dot {
+  fill: var(--timeline-gap-dot);
+}
+
+/* Loopbacks */
+.loopback {
+  stroke-opacity: var(--tl-loopback-default-opacity);
+  transition: stroke-opacity 120ms ease, stroke-width 120ms ease;
+}
+.loopback.highlight {
+  stroke-opacity: 1;
+  stroke-width: 2.5;
+}
+
+/* Time axis */
+.axis-baseline {
+  stroke: var(--tl-axis-line);
+  stroke-width: 1;
+  shape-rendering: crispEdges;
+}
+.axis-tick {
+  stroke: var(--tl-axis-tick);
+  stroke-width: 1;
+  shape-rendering: crispEdges;
+}
+.axis-label {
+  font-size: 11px;
+  fill: var(--tl-axis-label);
+  font-family: var(--sl-font-sans, system-ui, sans-serif);
+  font-variant-numeric: tabular-nums;
+}
+
+/* Legend */
+.timeline-legend {
+  display: flex;
+  align-items: center;
+  gap: 18px;
+  padding: 14px 0 4px;
+  margin-top: 8px;
+  border-top: 1px solid var(--border-subtle, rgba(226, 232, 240, 0.6));
+  flex-wrap: wrap;
+}
+.legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: var(--tl-text-strong);
+}
+.legend-swatch {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+  background: var(--muted);
+}
+.legend-swatch--gap {
+  background:
+    radial-gradient(circle, var(--timeline-gap-dot) 0.6px, transparent 1.2px),
+    var(--timeline-gap-fill);
+  background-size: 5px 5px;
+  border: 1px solid var(--tl-row-divider);
+}
+.legend-loopback {
+  /* Inline SVG arc + chevron; inherits color from the legend-item color, so
+     it tracks the rest of the legend chrome in both themes. */
+  color: var(--accent, #3b82f6);
+  flex-shrink: 0;
+}
+
+/* Tooltip */
+.timeline-tooltip {
+  position: fixed;
+  z-index: 1000;
+  background: var(--bg, #fff);
+  border: 1px solid var(--border, #e2e8f0);
+  border-radius: 8px;
+  box-shadow: 0 10px 28px rgba(15, 23, 42, 0.12), 0 2px 6px rgba(15, 23, 42, 0.08);
+  padding: 10px 12px;
+  pointer-events: none;
+  min-width: 200px;
+  max-width: 280px;
+  font-size: 12px;
+  line-height: 1.55;
+  color: var(--fg, #0f172a);
+}
+.tooltip-header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-weight: 600;
+  margin-bottom: 6px;
+  padding-bottom: 6px;
+  border-bottom: 1px solid var(--border-subtle, rgba(226, 232, 240, 0.6));
+}
+.tooltip-hue-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+.tooltip-header-sub {
+  font-weight: 400;
+  color: var(--tl-text-strong);
+  font-size: 11px;
+}
+.tooltip-bead-sub {
+  font-size: 11px;
+  color: var(--tl-text-strong);
+  margin-top: -2px;
+  margin-bottom: 4px;
+  line-height: 1.35;
+}
+.tooltip-bead-id {
+  font-family: var(--sl-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 10.5px;
+  background: var(--tl-row-alt, rgba(148, 163, 184, 0.12));
+  padding: 1px 5px;
+  border-radius: 3px;
+  margin-right: 4px;
+}
+.tooltip-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 14px;
+}
+.tooltip-label {
+  color: var(--tl-text-strong);
+  font-weight: 500;
+}
+.tooltip-value {
+  font-family: var(--sl-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-variant-numeric: tabular-nums;
+  color: var(--fg, #0f172a);
+}
+.tooltip-status {
+  text-transform: capitalize;
+}
+.tooltip-status.status-completed { color: var(--status-completed); }
+.tooltip-status.status-running, .tooltip-status.status-in_progress { color: var(--status-running); }
+.tooltip-status.status-failed { color: var(--status-failed); }
+.tooltip-status.status-paused { color: var(--status-paused); }
+.tooltip-status.status-interrupted { color: var(--status-interrupted); }
+
+/* --- Iteration drawer --- */
+.iteration-drawer::part(panel) {
+  width: 420px;
+  max-width: 90vw;
+}
+.iteration-drawer::part(header) {
+  border-bottom: 1px solid var(--border-subtle, rgba(226, 232, 240, 0.6));
+}
+.drawer-body {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  font-size: 13px;
+  color: var(--fg, #0f172a);
+}
+.drawer-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0 0 4px;
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--fg, #0f172a);
+  outline: none;
+}
+.drawer-hue-dot {
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+}
+.drawer-title-sub {
+  font-weight: 400;
+  color: var(--tl-text-strong);
+  font-size: 13px;
+}
+.drawer-status-row {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 12px;
+  border-radius: 999px;
+  background: var(--bg-secondary, #f8fafc);
+  align-self: flex-start;
+}
+.drawer-status-pill {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+}
+.drawer-status-text {
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: capitalize;
+}
+.drawer-status-text.status-completed { color: var(--status-completed); }
+.drawer-status-text.status-running, .drawer-status-text.status-in_progress { color: var(--status-running); }
+.drawer-status-text.status-failed { color: var(--status-failed); }
+.drawer-fields {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 8px 18px;
+  margin: 0;
+}
+.drawer-label {
+  color: var(--tl-text-strong);
+  font-weight: 500;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  align-self: center;
+}
+.drawer-value {
+  margin: 0;
+  font-family: var(--sl-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-variant-numeric: tabular-nums;
+  color: var(--fg, #0f172a);
+}
+.drawer-bead {
+  font-family: inherit;
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+.drawer-bead-id {
+  font-family: var(--sl-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 11px;
+  background: var(--tl-row-alt, rgba(148, 163, 184, 0.12));
+  padding: 1px 6px;
+  border-radius: 3px;
+}
+.drawer-raw-json {
+  margin-top: 4px;
+}
+.drawer-raw-json summary {
+  cursor: pointer;
+  color: var(--tl-text-strong);
+  font-size: 12px;
+  user-select: none;
+}
+.drawer-raw-json pre {
+  font-size: 11px;
+  font-family: var(--sl-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  background: var(--bg-secondary, #f8fafc);
+  border: 1px solid var(--border, #e2e8f0);
+  border-radius: 6px;
+  padding: 10px;
+  overflow-x: auto;
+  white-space: pre;
+  margin-top: 6px;
+  max-height: 280px;
+}
+.drawer-run-detail-link {
+  color: var(--accent, #3b82f6);
+  text-decoration: none;
+  font-size: 13px;
+  font-weight: 500;
+}
+.drawer-run-detail-link:hover {
+  text-decoration: underline;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .timeline-bar,
+  .loopback {
+    transition: none;
+  }
+}
+
 .action-btn:disabled:hover {
   background: var(--bg-secondary);
   color: inherit;
@@ -568,6 +1169,12 @@ h1, h2, h3, h4, h5, h6 {
 }
 
 /* Pipeline timing bar */
+.pipeline-timing-bar-actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-bottom: 8px;
+}
+
 .pipeline-timing-bar-container {
   margin-top: 8px;
 }
@@ -3133,6 +3740,9 @@ sl-option.template-grouped:focus::part(suffix) {
 
 .sidebar.collapsed .sidebar-new-run-btn-primary {
   padding: 8px;
+  /* Chevron half is hidden — drop the divider so the button reads as a
+     single icon control, not a button with a stray edge. */
+  border-right: 0;
 }
 
 /* Stage restart button */
@@ -7805,3 +8415,269 @@ sl-dialog.markdown-dialog::part(body) {
   color: var(--fg-muted);
   gap: 8px;
 }
+
+/* ===========================================================================
+ * Help mode (W-061 prototype, prototype/W-061-help-mode-toggle)
+ *
+ * Two concerns:
+ *   1. The right-edge "Docs" tab (.help-edge-tab) — always visible at 75%
+ *      opacity, fully opaque on hover/active.
+ *   2. Per-surface "?" badges (.help-badge) — hidden until body has the
+ *      .help-mode-active class.
+ *
+ * Colour: violet (~#7c3aed) — deliberately chosen so help mode reads as
+ * "informational / secondary" and never competes with the blue used for
+ * primary actions + running state, the green used for completed, the
+ * orange used for caution, or the red used for failed.
+ *
+ * Animation: each badge radiates a slow sonar wave outward and fades to
+ * transparent, like a discoverability signal. `prefers-reduced-motion`
+ * collapses the wave to a static dim halo.
+ * ===========================================================================
+ */
+
+/* --- Edge tab --------------------------------------------------------- */
+
+.help-edge-tab-root {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 1000;
+}
+
+/* Vertical pill anchored ~100px from the top of the viewport (deliberately
+   off-centre so it sits above the eye line and doesn't compete with
+   sidebar/main content for the visual centre). */
+.help-edge-tab {
+  position: fixed;
+  right: 0;
+  top: 100px;
+  transform: translateX(0);
+  transform-origin: right center;
+  pointer-events: auto;
+
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  /* Sized to wrap the rotated content (icon ~20px + 10px gap + "Docs"
+     label ~38px ≈ 68px length, 20px max thickness). Height bumped +25%
+     (84 → 105) per the user's request to give the rotated content more
+     padding at the top and bottom of the tab. */
+  width: 30px;
+  height: 105px;
+  padding: 0;
+  border: 1px solid #c4b5fd; /* violet-300 */
+  border-right: none;
+  border-top-left-radius: 8px;
+  border-bottom-left-radius: 8px;
+  background: rgba(124, 58, 237, 0.1); /* violet-600 @ 10% */
+  color: #5b21b6; /* violet-800 */
+  font-size: 16px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  cursor: pointer;
+  opacity: 0.75;
+  box-shadow: -2px 0 8px rgba(0, 0, 0, 0.06);
+  transition: opacity 160ms ease, background-color 120ms ease, color 120ms ease,
+    transform 180ms ease, box-shadow 180ms ease;
+}
+
+.help-edge-tab:hover,
+.help-edge-tab:focus-visible {
+  opacity: 1;
+  color: #4c1d95; /* violet-900 */
+  background: rgba(124, 58, 237, 0.18);
+  transform: translateX(-2px);
+  box-shadow: -4px 0 12px rgba(0, 0, 0, 0.08);
+  outline: none;
+}
+
+.help-edge-tab:focus-visible {
+  box-shadow: -4px 0 12px rgba(0, 0, 0, 0.08), 0 0 0 2px #7c3aed;
+}
+
+.help-edge-tab--active {
+  opacity: 1;
+  background: #7c3aed; /* violet-600 */
+  color: #fff;
+  border-color: #6d28d9; /* violet-700 */
+}
+
+.help-edge-tab--active:hover,
+.help-edge-tab--active:focus-visible {
+  background: #6d28d9;
+  color: #fff;
+}
+
+/* Inner row is icon + "Docs". Rotating the entire row -90deg (counter-
+   clockwise) makes both the icon and the label share the same rotation,
+   reading bottom-to-top along the right edge (head tilted left). */
+.help-edge-tab__inner {
+  display: inline-flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 10px;
+  transform: rotate(-90deg);
+  transform-origin: center center;
+  white-space: nowrap;
+}
+
+.help-edge-tab__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.help-edge-tab__label {
+  /* Matches the sidebar's WORCA wordmark (.logo-text) — JetBrains Mono
+     family + bold weight + wide letter-spacing — so the affordance reads
+     as part of the brand vocabulary rather than a generic side tab. */
+  font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', monospace;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  line-height: 1;
+}
+
+/* --- Per-surface help badge ------------------------------------------- */
+
+/* Hidden by default. Once help-mode-active flips on the body, every badge
+   reveals at the top-right of its parent and emits a slow sonar wave that
+   radiates outward then fades.
+
+   The badge is a real <a> — keyboard reachable when visible, opens the
+   doc in a new tab, never depends on JS for click handling. */
+.help-badge {
+  display: none;
+  position: absolute;
+  /* Vertically centred on the host's right edge — gives the sonar wave
+     equal headroom above and below the badge so it doesn't overflow
+     the host's bounding box. With disc 27px and wave max scale 1.5,
+     max wave diameter is ~40px → fits inside any host ≥ 40px tall
+     (typical sl-tab ~40px, panel headers larger). */
+  top: 50%;
+  right: 6px;
+  transform: translateY(-50%);
+  z-index: 5;
+
+  align-items: center;
+  justify-content: center;
+  /* Solid disc 27×27 — entire badge scaled up 50% (18 → 27). Icon, wave
+     base, and clickable hit target all grow proportionally. */
+  width: 27px;
+  height: 27px;
+  border-radius: 50%;
+  /* Solid disc at 75% opacity — rgba on the background only so the
+     ::after sonar wave's own opacity animation (0.55 → 0) isn't dimmed
+     by parent inheritance. The white glyph stays fully visible. */
+  background: rgba(124, 58, 237, 0.75); /* violet-600 @ 75% */
+  color: #fff;
+  text-decoration: none;
+  transition: transform 120ms ease, background-color 120ms ease;
+}
+
+/* Plain text "?" glyph — no container artifact (lucide's question-mark
+   variants all wrap the ? in some outline shape). Sized + weighted to
+   fill the 27px disc with a comfortable optical balance. */
+.help-badge__glyph {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-family: var(--sl-font-sans, system-ui, sans-serif);
+  font-size: 18px;
+  font-weight: 700;
+  line-height: 1;
+  /* Most "?" glyphs sit slightly above the optical centre of their
+     em-box because of the descender-free shape. Nudge down 1px so it
+     reads centred in the disc. */
+  margin-top: 1px;
+}
+
+/* The sonar wave — a same-colour pseudo-element behind the badge that
+   slowly grows outward and fades. Sits at z-index 0 (badge itself is
+   at z-index 5) so it appears under the badge during expansion. */
+.help-badge::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  background: #7c3aed;
+  opacity: 0;
+  z-index: -1;
+  pointer-events: none;
+}
+
+body.help-mode-active .help-badge {
+  display: inline-flex;
+}
+
+body.help-mode-active .help-badge::after {
+  animation: help-badge-sonar 2.4s ease-out infinite;
+}
+
+/* Auto-relative any direct parent of a badge so absolute positioning has
+   a containing block. Modern browsers (Chrome 105+, Safari 15.4+,
+   Firefox 121+) all support :has(). For sl-tab specifically, also force
+   overflow: visible so the badge (and especially the sonar wave) isn't
+   clipped against the tab strip's edge. */
+body.help-mode-active *:has(> .help-badge) {
+  position: relative;
+}
+
+body.help-mode-active sl-tab {
+  overflow: visible;
+}
+
+.help-badge:hover,
+.help-badge:focus-visible {
+  /* Compose the hover lift with the vertical-centre translate so the
+     badge doesn't jump when hovered. */
+  transform: translateY(-50%) scale(1.1);
+  /* Full opacity on hover so the affordance reads stronger. */
+  background: #6d28d9; /* violet-700, opaque */
+  outline: none;
+}
+
+/* Sonar wave: scale 1 → 1.5 from the 27px badge → max diameter ~40px,
+   centred on a badge that's vertically centred on the host. Wave fits
+   the host's bounding box on any host ≥ 40px tall (typical sl-tab
+   ~40px, panel headers larger; thin inline hosts may graze the edge). */
+@keyframes help-badge-sonar {
+  0% {
+    transform: scale(1);
+    opacity: 0.55;
+  }
+  100% {
+    transform: scale(1.5);
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  body.help-mode-active .help-badge::after {
+    animation: none;
+    opacity: 0.22;
+    transform: scale(1.3);
+  }
+  .help-edge-tab {
+    transition: none;
+  }
+}
+
+/* Dark-mode — violet stays violet, but we lift the idle background so it
+   doesn't blend into dark panels. */
+:root[data-theme='dark'] .help-edge-tab,
+.sl-theme-dark .help-edge-tab {
+  background: rgba(124, 58, 237, 0.22);
+  color: #e9d5ff; /* violet-200 */
+  border-color: #6d28d9;
+  box-shadow: -2px 0 8px rgba(0, 0, 0, 0.4);
+}
+
+:root[data-theme='dark'] .help-edge-tab:hover,
+:root[data-theme='dark'] .help-edge-tab:focus-visible,
+.sl-theme-dark .help-edge-tab:hover,
+.sl-theme-dark .help-edge-tab:focus-visible {
+  background: rgba(124, 58, 237, 0.35);
+  color: #f5f3ff;
+}