@runwisp/ui 1.5.0 → 1.5.1

package/src/lib/components/dashboard/run-filters.ts

@@ -2,17 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { TRIGGERS, type Trigger } from "@runwisp/common";
+import { TRIGGER_LABELS } from "./run-helpers.js";
 
 /**
- * The single filter shape shared by the runs list, the filter popover, the
- * SSE-merge source, and the bulk selector. Every field beyond `search` and
- * `sortDirection` is an optional dimension applied server-side; the zero
- * value (`emptyRunFilters`) matches every run.
- *
- * `statuses` is a multi-select set joined to a comma-separated string only at
- * the two wire boundaries (the list query and the bulk selector). Time bounds
- * are absolute RFC3339 instants — presets resolve to `now − delta` at apply
- * time so a live SSE row created after the boundary keeps matching.
+ * The filter shared by the runs list, the filter popover, the SSE-merge source
+ * and the bulk selector. Time bounds are absolute RFC3339 instants, so a live
+ * SSE row created after a preset was applied keeps matching.
  */
 export interface RunsListFilters {
     search: string;
@@ -20,52 +15,38 @@ export interface RunsListFilters {
     sortDirection: "asc" | "desc" | "";
     // Optional dimensions explicitly admit `undefined` so a dimension can be
     // cleared by reassignment (`{ ...f, x: undefined }`) under the project's
-    // exactOptionalPropertyTypes — a fresh object reference is what re-triggers
+    // exactOptionalPropertyTypes, a fresh object reference is what re-triggers
     // the parent's fetch effect through several levels of `bind:`.
     taskName?: string | undefined;
     createdAfter?: string | undefined;
     createdBefore?: string | undefined;
     triggeredBy?: string | undefined;
-    // A human exit-code expression — a bare code (`137`), a comparison (`>100`,
-    // `<=150`), or a space-separated combination (`>100 <150`). Normalized to an
-    // inclusive [min, max] range (`exitCodeRange`) at the wire boundary; the
-    // server only ever sees `exitCodeMin` / `exitCodeMax`.
+    // An exit-code expression such as `137`, `>100` or `>100 <150`; see
+    // parseExitCodeRange.
     exitCode?: string | undefined;
     retriesOnly?: boolean | undefined;
 }
 
-/** A fresh default filter — no dimensions active, newest-first. */
+/** A fresh default filter, no dimensions active, newest-first. */
 export function emptyRunFilters(): RunsListFilters {
     return { search: "", statuses: [], sortDirection: "desc" };
 }
 
 /**
- * Reserved `status` token the "Failed" browse filter sends instead of a fixed
- * end-reason list. The server (splitFailureToken in api_types.go) strips it and
- * matches on each run's persisted `isFailure` bit, so the browse filter agrees
- * with the attention badges, the failed stat, and notifications — all of which
- * follow the per-task `failures` policy. It is not a real status/end-reason, so
- * it OR-combines with the other buckets. Must match `failureStatusToken` in the
- * daemon.
+ * Reserved `status` token for the "Failed" filter. The daemon matches it on each
+ * run's `isFailure` bit (per-task `failures` policy) instead of a fixed
+ * end-reason list. Must match `failureStatusToken` in the daemon.
  */
 export const FAILURE_STATUS_TOKEN = "failure";
 
 /**
- * Outcome buckets: the 14 individual run statuses collapsed into five
- * plain-language groups, so the common case is a five-item pick instead of a
- * flat checklist. Each bucket is purely a UI grouping over `statuses` — toggling
- * one adds/removes its members, and the popover's "Advanced" section still
- * exposes the individual statuses for surgical filters (e.g. only `timeout`).
- *
- * Every status appears in exactly one bucket; `Failed` is the failure sentinel,
- * which the server resolves to each run's `isFailure` bit. `dot` mirrors that
- * group's color in
- * RUN_STATUS_CONFIG so the bucket reads at a glance.
+ * Outcome buckets: a UI grouping of the individual run statuses into five
+ * plain-language picks. The popover's "Advanced" section still exposes the
+ * individual statuses. `dot` mirrors the group's color in RUN_STATUS_CONFIG.
  */
 export interface StatusBucket {
     key: string;
     label: string;
-    /** Tailwind background class for the bucket's status dot. */
     dot: string;
     statuses: readonly string[];
 }
@@ -95,7 +76,6 @@ export const STATUS_BUCKETS: readonly StatusBucket[] = [
 
 export type BucketState = "on" | "partial" | "off";
 
-/** Whether none, some, or all of a bucket's statuses are currently selected. */
 export function bucketState(statuses: string[], bucket: StatusBucket): BucketState {
     const set = new Set(statuses);
     const present = bucket.statuses.filter((s) => set.has(s)).length;
@@ -122,7 +102,7 @@ function exactBucket(statuses: string[]): StatusBucket | undefined {
 
 /**
  * The popover-managed dimensions, in display (most→least useful) order.
- * `task` only ever applies on the cross-task /runs view — on a single task's
+ * `task` only ever applies on the cross-task /runs view, on a single task's
  * page the task name is the page scope (injected at fetch time), never a
  * popover-set filter, so it stays absent from those filters and is not counted.
  */
@@ -137,7 +117,6 @@ const DIMENSION_ORDER: FilterDimension[] = [
     "retries",
 ];
 
-/** Whether a single dimension is currently constraining the result set. */
 export function dimensionActive(f: RunsListFilters, dim: FilterDimension): boolean {
     switch (dim) {
         case "status":
@@ -155,17 +134,16 @@ export function dimensionActive(f: RunsListFilters, dim: FilterDimension): boole
     }
 }
 
-/** The active dimensions, in display order — drives the chip row. */
+/** The active dimensions, in display order, drives the chip row. */
 export function activeDimensions(f: RunsListFilters): FilterDimension[] {
     return DIMENSION_ORDER.filter((dim) => dimensionActive(f, dim));
 }
 
-/** How many dimensions are active — the count badge on the Filter button. */
+/** How many dimensions are active, the count badge on the Filter button. */
 export function activeFilterCount(f: RunsListFilters): number {
     return activeDimensions(f).length;
 }
 
-/** Reset one dimension, leaving the others (and search/sort) untouched. */
 export function clearDimension(f: RunsListFilters, dim: FilterDimension): RunsListFilters {
     switch (dim) {
         case "status":
@@ -190,47 +168,20 @@ export function humanizeStatus(status: string): string {
     return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 }
 
-/**
- * Descriptive label for a run's trigger source — fuller than the one-word row
- * badge (`formatTriggeredByLabel`) for the "cron"/"station"/"service"/"startup"
- * sources, where the extra words disambiguate (e.g. "REST API" vs a bare
- * "API"). "ui", "cli" and "hook" already read fine as their bare badge word,
- * so those three match `formatTriggeredByLabel` exactly.
- *
- * Note `cron` covers both on-time schedule firings and catch-up for missed
- * runs, and `startup` is specifically `run_on_start` (not catch-up).
- */
+/** Descriptive label for a run's trigger source (see {@link TRIGGER_LABELS}). */
 export function triggerDescription(trigger: string): string {
-    switch (trigger) {
-        case "cron":
-            return "Scheduled (cron)";
-        case "api":
-            return "REST API";
-        case "ui":
-            return "UI";
-        case "cli":
-            return "CLI";
-        case "station":
-            return "Control plane";
-        case "service":
-            return "Service auto-start";
-        case "startup":
-            return "On daemon start";
-        case "hook":
-            return "Hook";
-        default:
-            return humanizeStatus(trigger);
-    }
+    const known = TRIGGERS.find((t) => t === trigger);
+    return known ? TRIGGER_LABELS[known].long : humanizeStatus(trigger);
 }
 
 /**
  * The triggers offered in the filter dropdown. `station` is intentionally
- * excluded for now — control-plane runs still carry the `station` trigger, but
+ * excluded for now, control-plane runs still carry the `station` trigger, but
  * it isn't a selectable filter dimension.
  */
 export const FILTERABLE_TRIGGERS: readonly Trigger[] = TRIGGERS.filter((t) => t !== "station");
 
-/** Chip label for the status dimension — names a whole bucket when it matches. */
+/** Chip label for the status dimension, names a whole bucket when it matches. */
 export function statusChipLabel(statuses: string[]): string {
     const bucket = exactBucket(statuses);
     if (bucket) return bucket.label;
@@ -239,15 +190,6 @@ export function statusChipLabel(statuses: string[]): string {
     return `${String(statuses.length)} statuses`;
 }
 
-// --- Time helpers --------------------------------------------------------
-//
-// A bare calendar day (`YYYY-MM-DD` from a native date input) maps to a local
-// instant: the "from" edge is that day's 00:00, the "to" edge is its end
-// (23:59:59.999) so picking the same day for both bounds — or the one-click
-// "on day" shortcut — captures the whole day and round-trips back to the same
-// date in the inputs. Bounds are stored as absolute RFC3339 (UTC) instants, the
-// shape the list query and SSE-merge filter already expect.
-
 /** Parse `YYYY-MM-DD` into the local Date for that day, or null if malformed. */
 function localDay(dateStr: string): Date | null {
     const parts = dateStr.split("-");
@@ -295,14 +237,6 @@ export function isWholeDay(after?: string, before?: string): boolean {
     );
 }
 
-// --- Exit-code expression ------------------------------------------------
-//
-// The popover takes a free-form exit-code expression and normalizes it to an
-// inclusive integer [min, max] range — the shape the server gates on. Because
-// exit codes are integers, a strict comparison collapses to an inclusive
-// bound: `>100` is min 101, `<150` is max 149. Tokens combine (`>100 <150`),
-// and a bare number is an exact match (min = max = n).
-
 export interface ExitCodeRange {
     min?: number;
     max?: number;
@@ -311,10 +245,10 @@ export interface ExitCodeRange {
 const EXIT_CODE_TOKEN = /^(>=|<=|>|<)?(-?\d+)$/;
 
 /**
- * Parse an exit-code expression into an inclusive [min, max] range. Returns
- * `valid: false` if any token is unparseable, so the UI can flag a typo
- * instead of silently applying half of it. An empty expression is valid with
- * no bounds (no constraint).
+ * Parse an exit-code expression into the inclusive integer range the server
+ * filters on: `>100` is min 101, `<150` is max 149, a bare number is an exact
+ * match, and tokens combine. Any unparseable token makes the whole expression
+ * invalid so the UI can flag the typo. An empty expression is valid and unbounded.
  */
 export function parseExitCodeRange(expr: string): { range: ExitCodeRange; valid: boolean } {
     const range: ExitCodeRange = {};
@@ -353,13 +287,12 @@ export function exitCodeRange(expr: string | undefined): ExitCodeRange {
     return valid ? range : {};
 }
 
-/** True when the expression resolves to at least one bound (a real filter). */
 export function exitCodeRangeActive(expr: string | undefined): boolean {
     const { min, max } = exitCodeRange(expr);
     return min !== undefined || max !== undefined;
 }
 
-/** True when the expression is empty or fully parseable — drives input validation. */
+/** True when the expression is empty or fully parseable, drives input validation. */
 export function isExitCodeExprValid(expr: string): boolean {
     return parseExitCodeRange(expr).valid;
 }

package/src/lib/components/dashboard/run-helpers.test.ts

@@ -10,8 +10,17 @@ import {
     runRetryLabel,
     runUsageLabel,
     instanceSuffix,
+    runLogDownloadUrl,
 } from "./run-helpers.js";
 
+describe("runLogDownloadUrl", () => {
+    it("points at the daemon's raw log route", () => {
+        expect(runLogDownloadUrl("01J0000000000000000000000A")).toBe(
+            "/api/runs/01J0000000000000000000000A/log/raw",
+        );
+    });
+});
+
 describe("runVerdict", () => {
     it("phrases a timed outcome so a duration reads after it", () => {
         expect(runVerdict("succeeded")).toEqual({ verb: "succeeded in", timed: true });

package/src/lib/components/dashboard/run-helpers.ts

@@ -1,25 +1,17 @@
 // SPDX-FileCopyrightText: PoppyCake, s.r.o.
 // SPDX-License-Identifier: Apache-2.0
 
-import type { Run, RunStatus } from "@runwisp/common";
+import type { APIPaths, Run, RunStatus, Trigger } from "@runwisp/common";
 import { formatBytes, formatDuration } from "../../utils/format.js";
 
 export interface RunVerdict {
     /** Verb phrase for the outcome, ending in its preposition when `timed`. */
     verb: string;
-    /**
-     * Whether the phrase expects a duration after it. False for statuses that
-     * never produced one (nothing ran, or nothing has yet), so the caller
-     * renders the verb alone rather than "skipped after —".
-     */
+    /** Whether a duration follows the verb; false when nothing ran yet. */
     timed: boolean;
 }
 
-/**
- * The run's outcome as a verb phrase, so a detail view can state it as one
- * sentence ("succeeded in 933ms") instead of a status badge competing with a
- * separate duration readout for the same glance.
- */
+// The run's outcome as a verb phrase, read as one sentence: "succeeded in 933ms".
 const RUN_VERDICTS: Record<RunStatus, RunVerdict> = {
     succeeded: { verb: "succeeded in", timed: true },
     failed: { verb: "failed after", timed: true },
@@ -54,12 +46,8 @@ export function runDuration(
 }
 
 /**
- * Gap between when a run was scheduled (`createdAt`, the cron tick) and when
- * it actually started (`startedAt`), formatted — or undefined when the two are
- * within a second of each other. This is the visible face of `jitter`: a
- * jittered run is created at its tick but starts later inside the window, and
- * this is by how much. It also surfaces queue-wait, since a queued run is
- * created when it joins the line and started when the line clears.
+ * How long a run waited between `createdAt` and `startedAt` (jitter or queue
+ * wait), or undefined when it started within a second.
  */
 export function runStartDelay(run: Pick<Run, "createdAt" | "startedAt">): string | undefined {
     if (!run.startedAt) return undefined;
@@ -68,14 +56,7 @@ export function runStartDelay(run: Pick<Run, "createdAt" | "startedAt">): string
     return formatDuration(delay);
 }
 
-/**
- * Display suffix for a run's instance slot. A service configured with more than
- * one instance gets a 1-based suffix (`#1`, `#2`, …) on every one of its runs;
- * a single-instance task (or any non-service, where `instanceCount` is 1)
- * returns an empty string so the bare task name is shown. `instanceIndex` is
- * the stored 0-based slot; `instanceCount` is the task's currently configured
- * instance count.
- */
+/** 1-based `#N` suffix for a multi-instance service run, else "". */
 export function instanceSuffix(instanceIndex: number, instanceCount: number): string {
     if (instanceCount > 1) {
         return `#${String(instanceIndex + 1)}`;
@@ -83,23 +64,32 @@ export function instanceSuffix(instanceIndex: number, instanceCount: number): st
     return "";
 }
 
+// Typed against the generated paths so a route rename fails the build.
+const RAW_LOG_PATH: keyof APIPaths = "/api/runs/{runId}/log/raw";
+
+/** The full log of a run as one plain-text download. */
+export function runLogDownloadUrl(runId: string): string {
+    return RAW_LOG_PATH.replace("{runId}", encodeURIComponent(runId));
+}
+
+/** Labels per trigger source: `short` for the row badge, `long` for descriptions. */
+export const TRIGGER_LABELS: Record<Trigger, { short: string; long: string }> = {
+    cron: { short: "Cron", long: "Scheduled (cron)" },
+    api: { short: "API", long: "REST API" },
+    ui: { short: "UI", long: "UI" },
+    cli: { short: "CLI", long: "CLI" },
+    station: { short: "Station", long: "Control plane" },
+    service: { short: "Service", long: "Service auto-start" },
+    startup: { short: "Startup", long: "On daemon start" },
+    hook: { short: "Hook", long: "Hook" },
+};
+
 /** Human label for why a run fired (the `triggeredBy` source). */
 export function formatTriggeredByLabel(triggeredBy: Run["triggeredBy"]): string {
-    if (triggeredBy === "api") return "API";
-    if (triggeredBy === "ui") return "UI";
-    if (triggeredBy === "cli") return "CLI";
-    if (triggeredBy === "cron") return "Cron";
-    if (triggeredBy === "service") return "Service";
-    if (triggeredBy === "startup") return "Startup";
-    if (triggeredBy === "hook") return "Hook";
-    return "Station";
+    return TRIGGER_LABELS[triggeredBy].short;
 }
 
-/**
- * "retry #N" label when a run is a retry of an earlier one, else undefined.
- * A run is a retry if it carries a positive attempt number or points back at
- * the run it re-attempts.
- */
+/** "retry #N" when the run re-attempts an earlier one, else undefined. */
 export function runRetryLabel(run: Pick<Run, "retryAttempt" | "retryOfRunId">): string | undefined {
     if (run.retryAttempt > 0 || run.retryOfRunId) {
         return `retry #${String(run.retryAttempt)}`;

package/src/lib/components/data-grid-selection.ts

@@ -1,14 +1,6 @@
 // SPDX-FileCopyrightText: PoppyCake, s.r.o.
 // SPDX-License-Identifier: Apache-2.0
 
-// DataGrid's header checkbox (checked / indeterminate / unchecked) must
-// reflect which rows on the current page are ACTUALLY selected, not merely
-// how many rows are selected. A bare count comparison is wrong the moment
-// `selectedRows` holds a different set of rows than `pagedRows` but happens
-// to be the same size — e.g. rows selected on a page the grid has since
-// paged/filtered away from. Extracted so the membership check is unit
-// testable without a component-render harness.
-
 export interface SelectionState {
     allSelected: boolean;
     someSelected: boolean;
@@ -17,7 +9,8 @@ export interface SelectionState {
 /**
  * Header checkbox state for `pagedRows`: fully checked only when every row
  * currently on the page is selected, indeterminate when some (but not all)
- * of them are. Matches rows by `rowKey`, not by array position or count.
+ * of them are. Matches rows by `rowKey`, not by count: the selection can
+ * hold rows from a page the grid has since moved away from.
  */
 export function selectionState<T>(
     pagedRows: readonly T[],

package/src/lib/components/filter-spec.ts

@@ -3,7 +3,7 @@
 
 // Declarative filter spec. A `FilterField[]` + one bound `FilterValues` object
 // drives <FilterBar>, the client engine (`applyFilters`), and the URL sync
-// helper — the same way DataGrid's `Column[]` drives the table. Add a field
+// helper, the same way DataGrid's `Column[]` drives the table. Add a field
 // type here, and every table that adopts it renders identically.
 
 import type { SelectOption } from "./Select.svelte";
@@ -44,7 +44,7 @@ export type FilterField =
           primary?: boolean;
       };
 
-// All values are strings — DOM inputs are string-valued and URL params are
+// All values are strings, DOM inputs are string-valued and URL params are
 // strings; the client engine coerces (e.g. Number()) where a field needs it.
 export type FilterValues = Record<string, string>;
 
@@ -65,7 +65,7 @@ export function isBlank(v: string | undefined): boolean {
     return !v || v === "all";
 }
 
-// Which value keys a field owns — daterange owns two, everything else one.
+// Which value keys a field owns, daterange owns two, everything else one.
 // Used by chips, active-state detection, clear, and URL (de)serialization so
 // none of them has to special-case the range type.
 export function fieldKeys(field: FilterField): string[] {

package/src/lib/log-console/LogCache.svelte.ts

@@ -14,7 +14,7 @@ import { visibleColumns } from "./ansi.js";
  */
 // Streams pinned to the front of the overlay, in render order. The companion
 // Set backs the membership test in `overlayRows`. Both are module-level,
-// immutable, and non-reactive — a fixed lookup table, not component state.
+// immutable, and non-reactive, a fixed lookup table, not component state.
 const PREFERRED_STREAM_ORDER = ["stdout", "stderr"] as const;
 const PREFERRED_STREAMS: ReadonlySet<string> = new Set(PREFERRED_STREAM_ORDER);
 

package/src/lib/log-console/ansi.ts

@@ -45,7 +45,7 @@ const ANSI_ESCAPE = /\x1b\[[0-9;?]*[A-Za-z]/g;
 const TAB_WIDTH = 8;
 
 // Count the visible columns a log line occupies once ANSI escape sequences
-// are stripped. Tabs are charged the full tab width — an over-estimate that
+// are stripped. Tabs are charged the full tab width, an over-estimate that
 // only adds trailing slack to the horizontal scroll surface, never clips.
 export function visibleColumns(text: string): number {
     let columns = 0;

package/src/lib/theme-tokens.css

@@ -1,7 +1,7 @@
 /* SPDX-FileCopyrightText: PoppyCake, s.r.o. */
 /* SPDX-License-Identifier: Apache-2.0 */
 
-/* RunWisp Design Tokens — plain CSS, no Tailwind directives.
+/* RunWisp Design Tokens, plain CSS, no Tailwind directives.
  *
  * Single source of truth for the OKLch palette and the semantic `--rw-*`
  * tokens that drive all apps:
@@ -19,7 +19,7 @@
  *   The union selector covers both. Light mode is the default.
  *
  * Webfonts are @imported here (not in theme.css) so every consumer that reads
- * these tokens also gets the faces they name — apps/docs imports this file
+ * these tokens also gets the faces they name, apps/docs imports this file
  * alone. Both families ship in the binary; nothing is fetched from a CDN.
  */
 
@@ -30,13 +30,13 @@
 @import "@fontsource-variable/geist-mono/index.css";
 
 :root {
-    /* Typography — body sans for prose, mono for all chrome and identifiers.
+    /* Typography, body sans for prose, mono for all chrome and identifiers.
      * Geist Mono is variable (100–900), so heading weight 800 is a real cut. */
     --rw-font-sans: "TASA Orbiter", system-ui, -apple-system, sans-serif;
     --rw-font-mono:
         "Geist Mono Variable", "Geist Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
 
-    /* Primary — Wisp Teal (brand = #0E7C86, the artifact's deep teal). Deeper
+    /* Primary, Wisp Teal (brand = #0E7C86, the artifact's deep teal). Deeper
      * and less cyan than Aurora (running/info) so the two stay distinct. */
     --rw-color-wisp-50: oklch(0.97 0.02 205);
     --rw-color-wisp-100: oklch(0.95 0.035 205);
@@ -50,7 +50,7 @@
     --rw-color-wisp-900: oklch(0.3 0.048 208);
     --rw-color-wisp-950: oklch(0.2 0.034 210);
 
-    /* Accent — Aurora Teal (running status = #13A0A8, a cyan-leaning teal) */
+    /* Accent, Aurora Teal (running status = #13A0A8, a cyan-leaning teal) */
     --rw-color-aurora-50: oklch(0.97 0.02 192);
     --rw-color-aurora-100: oklch(0.94 0.045 192);
     --rw-color-aurora-200: oklch(0.88 0.075 190);
@@ -62,7 +62,7 @@
     --rw-color-aurora-800: oklch(0.35 0.07 192);
     --rw-color-aurora-900: oklch(0.28 0.055 192);
 
-    /* Mist — teal-gray neutrals (the runbook's #F3F6F6 / #E0E7E7 /
+    /* Mist, teal-gray neutrals (the runbook's #F3F6F6 / #E0E7E7 /
      * #14262A / #0C1719 family). No purple tint; hue ~195-205, low chroma,
      * so bg-mist-* utilities agree with the new teal-black surfaces. The light
      * end stays near-neutral to match the desaturated canvas. */
@@ -78,7 +78,7 @@
     --rw-color-mist-900: oklch(0.266 0.025 204); /* ≈ #16292B */
     --rw-color-mist-950: oklch(0.195 0.016 208); /* ≈ #0C1719 */
 
-    /* Success — Field Green (success status = #1F9D57, a true grass green) */
+    /* Success, Field Green (success status = #1F9D57, a true grass green) */
     --rw-color-success-50: oklch(0.97 0.02 150);
     --rw-color-success-100: oklch(0.94 0.04 150);
     --rw-color-success-200: oklch(0.88 0.07 150);
@@ -88,7 +88,7 @@
     --rw-color-success-600: oklch(0.5 0.13 150);
     --rw-color-success-700: oklch(0.42 0.11 150);
 
-    /* Danger — Signal Red (failed status = #D6453D, a warm tomato red) */
+    /* Danger, Signal Red (failed status = #D6453D, a warm tomato red) */
     --rw-color-danger-50: oklch(0.97 0.016 27);
     --rw-color-danger-100: oklch(0.94 0.03 27);
     --rw-color-danger-200: oklch(0.88 0.06 27);
@@ -98,7 +98,7 @@
     --rw-color-danger-600: oklch(0.5 0.17 27);
     --rw-color-danger-700: oklch(0.42 0.145 27);
 
-    /* Warning — Ember Amber (stopped status = #D98324, a warm orange-amber) */
+    /* Warning, Ember Amber (stopped status = #D98324, a warm orange-amber) */
     --rw-color-warning-50: oklch(0.97 0.03 78);
     --rw-color-warning-100: oklch(0.94 0.07 74);
     --rw-color-warning-200: oklch(0.9 0.11 72);
@@ -108,7 +108,7 @@
     --rw-color-warning-600: oklch(0.6 0.14 62);
     --rw-color-warning-700: oklch(0.52 0.12 60);
 
-    /* ANSI console palette — 16-color map for the log console, tuned for
+    /* ANSI console palette, 16-color map for the log console, tuned for
      * its always-dark surface (no .dark override needed). Hues follow the
      * semantic scales: red→danger, green→success, yellow→warning,
      * blue→wisp, cyan→aurora, grays→mist. */
@@ -129,11 +129,11 @@
     --rw-ansi-bright-cyan: var(--rw-color-aurora-300);
     --rw-ansi-bright-white: var(--rw-color-mist-50);
 
-    /* Fixed-dark sibling palettes — the `--rw-con-*` log console (a "black box"
+    /* Fixed-dark sibling palettes, the `--rw-con-*` log console (a "black box"
      * device) and the `--rw-term-*`/`--rw-syn-*` website terminal surfaces both
      * keep their own dark palette in BOTH themes; they never flip light/dark. */
 
-    /* Console device surface — the log console instrument.
+    /* Console device surface, the log console instrument.
      * Exact values from the approved execution-detail design. */
     --rw-con-bg: #0e141b; /* body / gutter backing */
     --rw-con-panel: #11181f; /* toolbar + footer chrome */
@@ -141,7 +141,7 @@
     --rw-con-dim: #6c7d8c; /* footer + muted readouts */
     --rw-con-gutter: #3c4a58; /* line numbers + sentinel rule */
 
-    /* Terminal surface — always dark in both themes (website --term-* set) */
+    /* Terminal surface, always dark in both themes (website --term-* set) */
     --rw-term: #0a1116;
     --rw-term-2: #0d151b;
     --rw-term-line: #1d2932;
@@ -161,7 +161,7 @@
     --rw-syn-punc: #9aa7b0;
     --rw-syn-fn: #2fd4dd;
 
-    /* Elevation — light-mode drop shadows; flipped to `none` in dark so the
+    /* Elevation, light-mode drop shadows; flipped to `none` in dark so the
      * UI reads as borders-only there. */
     --rw-shadow-xs: 0 1px 2px rgba(16, 41, 43, 0.04);
     --rw-shadow-sm: 0 1px 2px rgba(16, 41, 43, 0.04), 0 12px 28px -20px rgba(16, 41, 43, 0.22);
@@ -169,7 +169,7 @@
     --rw-shadow-lg: 0 1px 2px rgba(16, 41, 43, 0.06), 0 30px 60px -28px rgba(16, 41, 43, 0.45);
     --rw-shadow-xl: 0 1px 2px rgba(16, 41, 43, 0.06), 0 40px 80px -30px rgba(16, 41, 43, 0.5);
 
-    /* Light-mode semantic tokens (default) — runbook palette (exact hex).
+    /* Light-mode semantic tokens (default), runbook palette (exact hex).
      *
      * The canvas carries only a whisper of the brand teal. The website can
      * afford a minty `--ground` because dark panes and terminals cover most
@@ -223,7 +223,7 @@
     --rw-warning-soft: rgba(196, 120, 26, 0.1);
     --rw-warning-soft-text: #c4781a;
     --rw-warning-soft-border: rgba(196, 120, 26, 0.25);
-    /* Info — matches primary teal */
+    /* Info, matches primary teal */
     --rw-info: #15a0a8;
     --rw-info-hover: #0e7c86;
     --rw-on-info: #ffffff;
@@ -235,7 +235,7 @@
     --rw-glass-blur: blur(12px);
 }
 
-/* Dark-mode semantic tokens — `.dark` class for Svelte apps, `[data-theme="dark"]`
+/* Dark-mode semantic tokens, `.dark` class for Svelte apps, `[data-theme="dark"]`
  * attribute for Starlight. Both selectors apply the same token set. */
 :root.dark,
 :root[data-theme="dark"] {
@@ -254,7 +254,7 @@
     --rw-outline-faint: #1d2932;
     --rw-ring: #2fd4dd;
     --rw-backdrop: rgba(4, 10, 12, 0.7);
-    /* Primary — bright teal in dark, matches info */
+    /* Primary, bright teal in dark, matches info */
     --rw-primary: #2fd4dd;
     --rw-primary-hover: #5fe3ea;
     --rw-primary-active: #5fe3ea;
@@ -284,7 +284,7 @@
     --rw-warning-soft: rgba(224, 165, 46, 0.14);
     --rw-warning-soft-text: #e0a52e;
     --rw-warning-soft-border: rgba(224, 165, 46, 0.28);
-    /* Info — bright teal in dark */
+    /* Info, bright teal in dark */
     --rw-info: #2fd4dd;
     --rw-info-hover: #5fe3ea;
     --rw-on-info: #04181a;
@@ -293,7 +293,7 @@
     --rw-info-soft-border: rgba(47, 212, 221, 0.28);
     /* Glass */
     --rw-glass: rgba(8, 15, 17, 0.9);
-    /* Elevation — borders-only in dark, no drop shadow */
+    /* Elevation, borders-only in dark, no drop shadow */
     --rw-shadow-xs: none;
     --rw-shadow-sm: none;
     --rw-shadow-md: none;
@@ -301,7 +301,7 @@
     --rw-shadow-xl: none;
 }
 
-/* Platform polish — focus ring, text selection, scrollbar. Lifted from
+/* Platform polish, focus ring, text selection, scrollbar. Lifted from
  * theme.css so apps/docs (no Tailwind) gets the same treatment as the
  * Svelte apps. */