@celestia-island/hikari 0.55.274 → 0.55.275

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.274",
+  "version": "0.55.275",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkBarChart.scss

@@ -40,15 +40,41 @@
     font-variant-numeric: tabular-nums;
   }
 
+  // Above-bar value label (showValues) — the same 10-unit voice as the
+  // axis, a step stronger so the count reads first.
+  &__value {
+    fill: rgb(var(--color-text) / 0.75);
+    font-size: 10px;
+    text-anchor: middle;
+    font-variant-numeric: tabular-nums;
+  }
+
+  // Slot mark (a bar's icon — the supership Star): a nested <svg> whose
+  // ink follows currentColor, so lucide's stroke picks up the axis voice
+  // without per-icon wiring.
+  &__xmark {
+    color: rgb(var(--color-text) / 0.55);
+  }
+
   &__bar {
     fill: rgb(var(--color-primary));
     outline: none;
     cursor: pointer;
-    transition: filter 0.16s ease;
+    transition: filter 0.16s ease, opacity 0.16s ease;
 
     &:hover,
-    &:focus-visible {
+    &:focus-visible,
+    // Dim-pair head (activeIndex): keeps the hover lift while the
+    // pointer may sit anywhere — the host pairs bars by wiring
+    // activeIndex from the hover events.
+    &[data-hot] {
       filter: brightness(1.08) saturate(1.15);
     }
+
+    // Dim-pair follower: every other bar recedes, same ease family as
+    // the lift so the pair breathes together.
+    &[data-dim] {
+      opacity: 0.45;
+    }
   }
 }

package/src/components/HkBarChart.test.tsx

@@ -27,6 +27,10 @@ const BARS = [
   { label: "Wed", value: 0 },
 ];
 
+/** A tiny stand-in for a lucide glyph: any icon FUNCTION draws the
+ * 24-unit box the slot-mark wrapper maps onto its 12-unit mark. */
+const StarGlyph = () => <rect x="0" y="0" width="24" height="24" />;
+
 describe("HkBarChart", () => {
   it("renders one labeled bar per bucket and skips zero buckets' paths", () => {
     const el = mount(<HkBarChart bars={BARS} />);
@@ -59,4 +63,126 @@ describe("HkBarChart", () => {
       "weekly playtime",
     );
   });
+
+  // ── showValues ───────────────────────────────────────────────────
+
+  it("showValues renders formatValue above each bar and skips zero buckets", () => {
+    const el = mount(
+      <HkBarChart bars={BARS} showValues formatValue={(v) => `${Math.round(v / 3600)}h`} />,
+    );
+    const values = [...el.querySelectorAll(".hk-bar-chart__value")];
+    // The zero bucket (Wed) carries no label — the wowsp tier histogram's
+    // old labelY-null behavior: an empty slot never shows a stray "0".
+    expect(values.map((t) => t.textContent)).toEqual(["1h", "2h"]);
+    // Each label's baseline sits exactly 5 units above its bar's top —
+    // the path's y coordinates sit at odd indices ("M x0 y L x0 y… Q x y
+    // x y …"), and their minimum IS the top.
+    const topOf = (d: string) => {
+      const nums = d.split(/[\sMLQAZ]+/).filter(Boolean).map(Number);
+      return Math.min(...nums.filter((_, i) => i % 2 === 1));
+    };
+    const tops = [...el.querySelectorAll(".hk-bar-chart__bar")].map((p) =>
+      topOf(p.getAttribute("d") ?? ""),
+    );
+    expect(Number(values[0].getAttribute("y"))).toBeCloseTo(tops[0] - 5, 6);
+    expect(Number(values[1].getAttribute("y"))).toBeCloseTo(tops[1] - 5, 6);
+  });
+
+  it("showValues off by default — old usage renders no value labels", () => {
+    const el = mount(<HkBarChart bars={BARS} />);
+    expect(el.querySelectorAll(".hk-bar-chart__value")).toHaveLength(0);
+  });
+
+  // ── hover event + activeIndex dim-pair ───────────────────────────
+
+  it("emits hover on bar mouseenter / mouseleave with focus / blur parity", () => {
+    const hovers: (number | null)[] = [];
+    const el = mount(<HkBarChart bars={BARS} onHover={(i) => hovers.push(i)} />);
+    const bars = [...el.querySelectorAll(".hk-bar-chart__bar")];
+    bars[0].dispatchEvent(new Event("mouseenter"));
+    bars[1].dispatchEvent(new Event("focus"));
+    bars[1].dispatchEvent(new Event("blur"));
+    bars[0].dispatchEvent(new Event("mouseleave"));
+    expect(hovers).toEqual([0, 1, null, null]);
+  });
+
+  it("activeIndex carries data-hot on the paired bar and data-dim on the others", () => {
+    const el = mount(<HkBarChart bars={BARS} activeIndex={0} />);
+    const bars = [...el.querySelectorAll(".hk-bar-chart__bar")];
+    expect(bars[0].getAttribute("data-hot")).toBe("true");
+    expect(bars[0].hasAttribute("data-dim")).toBe(false);
+    expect(bars[1].getAttribute("data-dim")).toBe("true");
+    expect(bars[1].hasAttribute("data-hot")).toBe(false);
+  });
+
+  it("defaults to no pair — no data-hot / data-dim anywhere", () => {
+    const el = mount(<HkBarChart bars={BARS} />);
+    expect(el.querySelector("[data-hot], [data-dim]")).toBeNull();
+  });
+
+  // ── icon slot mark (the supership Star) ──────────────────────────
+
+  it("renders a resolvable icon in place of the x-label text, sized and centered", () => {
+    const el = mount(
+      <HkBarChart
+        bars={[
+          { label: "10", value: 5, icon: StarGlyph },
+          { label: "11", value: 7 },
+        ]}
+      />,
+    );
+    const marks = [...el.querySelectorAll(".hk-bar-chart__xmark")];
+    expect(marks).toHaveLength(1);
+    // The nested-svg wrapper maps the 24-unit lucide box onto a 12-unit
+    // mark centered on slot 0 (centerX 182) at the x-label's optical
+    // center (baselineY 196 + 4).
+    expect(marks[0].getAttribute("viewBox")).toBe("0 0 24 24");
+    expect(marks[0].getAttribute("width")).toBe("12");
+    expect(marks[0].getAttribute("height")).toBe("12");
+    expect(marks[0].getAttribute("x")).toBe("176");
+    expect(marks[0].getAttribute("y")).toBe("200");
+    // The icon swapped out that slot's text; the other slot keeps its text.
+    expect([...el.querySelectorAll(".hk-bar-chart__x")].map((t) => t.textContent)).toEqual([
+      "11",
+    ]);
+    // The bar's aria string keeps the TEXT label, icon or not.
+    expect(el.querySelector(".hk-bar-chart__bar")?.getAttribute("aria-label")).toContain("10");
+  });
+
+  it("normalizes icons like HkPillToggleGroup — vnode passes through, junk falls back to text", () => {
+    const el = mount(
+      <HkBarChart
+        bars={[
+          { label: "a", value: 3, icon: <rect x="4" y="4" width="16" height="16" /> },
+          { label: "b", value: 4, icon: "not-an-icon" },
+        ]}
+      />,
+    );
+    // The prebuilt vnode rides the mark wrapper; the junk string does not
+    // blank the slot — it falls back to the text label.
+    expect(el.querySelectorAll(".hk-bar-chart__xmark")).toHaveLength(1);
+    expect(el.querySelectorAll(".hk-bar-chart__xmark rect")).toHaveLength(1);
+    expect([...el.querySelectorAll(".hk-bar-chart__x")].map((t) => t.textContent)).toEqual(["b"]);
+  });
+
+  // ── back-compat: the wowsp PlaytimeView usage surface ────────────
+
+  it("old-props usage renders exactly the old surface", () => {
+    const el = mount(
+      <HkBarChart
+        bars={BARS.map((b) => ({ label: b.label, value: b.value, hint: b.hint }))}
+        width={480}
+        formatValue={(v) => `${Math.round(v / 3600)}h`}
+      />,
+    );
+    expect(el.querySelectorAll(".hk-bar-chart__bar")).toHaveLength(2);
+    expect(el.querySelectorAll(".hk-bar-chart__value")).toHaveLength(0);
+    expect(el.querySelectorAll(".hk-bar-chart__xmark")).toHaveLength(0);
+    expect(el.querySelector("[data-hot], [data-dim]")).toBeNull();
+    expect([...el.querySelectorAll(".hk-bar-chart__x")].map((t) => t.textContent)).toEqual([
+      "Mon",
+      "Tue",
+      "Wed",
+    ]);
+  });
 });

package/src/components/HkBarChart.tsx

@@ -1,8 +1,43 @@
-import { computed, defineComponent, type PropType } from "vue";
+import { computed, defineComponent, h, type PropType, type VNode } from "vue";
 
 import { barLayout, type BarSlot } from "./barChart";
 import "./HkBarChart.scss";
 
+/** One bar entry. */
+export interface HkBarChartBar {
+  /** Text label under the slot — also the bar's aria string, even when
+   * an `icon` replaces the visible text. */
+  label: string;
+  value: number;
+  /** Hover/focus hint; defaults to `label: formatValue(value)`. */
+  hint?: string;
+  /** Optional slot mark rendered IN PLACE of the x-label text (the tier
+   * histogram's supership Star). Accepts EITHER a component (a lucide
+   * icon function, a defineComponent options object) or a prebuilt
+   * vnode — normalized exactly like HkPillToggleGroup's icon handling;
+   * anything else falls back to the text label (never a blank slot). */
+  icon?: unknown;
+}
+
+/** Normalize a bar icon to a renderable vnode — the HkPillToggleGroup
+ * convention verbatim: a component (function or options object) is
+ * instantiated with `h`; a prebuilt vnode passes through; anything
+ * else (string, number, null) renders nothing, and the caller falls
+ * back to the text label. */
+function resolveIcon(icon: unknown): VNode | null {
+  if (icon == null) return null;
+  if (typeof icon === "object") return icon as VNode;
+  if (typeof icon === "function") return h(icon as Parameters<typeof h>[0]);
+  return null;
+}
+
+/** The slot-mark box (wowsp's tier-star convention): lucide glyphs draw
+ * in a 24×24 box, so the wrapper nested <svg> maps that box onto a
+ * 12-unit mark centered on the x-label's optical center — the 10-unit
+ * text's baseline is baselineY + 14 and its glyph box spans
+ * ≈ baselineY + 6 … + 14, so a mark from +4 to +16 shares its center. */
+const BAR_MARK = { glyphBox: 24, size: 12, top: 4 } as const;
+
 /**
  * HkBarChart — one bar per bucket over a hand-drawn declarative SVG (no
  * chart library; the HkTreemap/HkCalendarHeatmap dependency-free line).
@@ -16,6 +51,15 @@ import "./HkBarChart.scss";
  * wowsp delegated-tooltip hook reads — hikari itself renders no native
  * title bubble).
  *
+ * The tier histogram's needs ride along as OPTIONAL props (wowsp
+ * ShipDistCharts): `showValues` paints formatValue(value) above each
+ * bar (empty slots carry no label), `hover` + `activeIndex` implement a
+ * dim-pair — the HOST wires activeIndex from the hover events, the bar
+ * at activeIndex carries `data-hot` and every other bar `data-dim` —
+ * and a bar's `icon` replaces its x-label text (the supership slot's
+ * nested-svg Star, positioned/sized here from the 24-unit lucide box).
+ * Defaults reproduce the old output exactly.
+ *
  * Dumb by design: the caller owns aggregation and passes the settled
  * buckets in. All geometry lives in ./barChart (pure, pinned by its own
  * tests).
@@ -27,7 +71,7 @@ export default defineComponent({
   props: {
     /** The bars, in axis order (oldest → newest for trend charts). */
     bars: {
-      type: Array as PropType<{ label: string; value: number; hint?: string }[]>,
+      type: Array as PropType<HkBarChartBar[]>,
       required: true,
     },
     /** Frame size (the SVG viewBox; CSS scales it). */
@@ -42,10 +86,25 @@ export default defineComponent({
     ariaLabel: { type: String, default: null },
     /** Rendered when every bucket is zero / the array is empty. */
     emptyText: { type: String, default: "No data" },
+    /** Paint formatValue(value) as a small label ABOVE each bar. Skip
+     * rule: bars with value <= 0 carry NO label (their slot stays an
+     * empty slot) — the wowsp tier histogram's old labelY-null behavior,
+     * so an unplayed bucket never shows a stray "0". */
+    showValues: { type: Boolean, default: false },
+    /** The dim-pair head: when set, the bar at this index carries
+     * `data-hot` (kept hover lift) and every other bar carries
+     * `data-dim` (≈0.45 opacity). The HOST implements the pair by
+     * wiring this from the `hover` events; null (the default) draws no
+     * pair at all. */
+    activeIndex: { type: Number as PropType<number | null>, default: null },
   },
   emits: {
     /** A bar was clicked (its bucket index). */
     select: (index: number) => typeof index === "number",
+    /** The pointer entered a bar (its bucket index) or left it / the
+     * keyboard focus moved onto or off one (focus/blur parity — null
+     * when the hover ended). */
+    hover: (index: number | null) => typeof index === "number" || index === null,
   },
   setup(props, { emit }) {
     const layout = computed(() =>
@@ -60,7 +119,12 @@ export default defineComponent({
         props.ariaLabel ??
         props.bars.map((b) => `${b.label} ${props.formatValue(b.value)}`).join(", "),
     );
-    const hintOf = (b: { label: string; value: number; hint?: string }, i: number): string =>
+    /** The dim-pair head, normalized: anything but a number (undefined,
+     * null, garbage) means "no pair". */
+    const active = computed(() =>
+      typeof props.activeIndex === "number" ? props.activeIndex : null,
+    );
+    const hintOf = (b: HkBarChartBar, i: number): string =>
       b.hint ?? `${b.label}: ${props.formatValue(b.value)}`;
 
     return () => {
@@ -90,23 +154,58 @@ export default defineComponent({
               </text>
             </g>
           ))}
-          {l.bars.map((s: BarSlot, i: number) => (
-            <g key={i}>
-              {s.path ? (
-                <path
-                  class="hk-bar-chart__bar"
-                  d={s.path}
-                  data-hint={hintOf(props.bars[i], i)}
-                  aria-label={hintOf(props.bars[i], i)}
-                  tabindex={0}
-                  onClick={() => emit("select", i)}
-                />
-              ) : null}
-              <text class="hk-bar-chart__x" x={s.centerX} y={l.baselineY + 14}>
-                {props.bars[i].label}
-              </text>
-            </g>
-          ))}
+          {l.bars.map((s: BarSlot, i: number) => {
+            const bar = props.bars[i];
+            const mark = resolveIcon(bar.icon);
+            return (
+              <g key={i}>
+                {s.path ? (
+                  <path
+                    class="hk-bar-chart__bar"
+                    d={s.path}
+                    data-hint={hintOf(bar, i)}
+                    aria-label={hintOf(bar, i)}
+                    tabindex={0}
+                    data-hot={active.value === i || undefined}
+                    data-dim={(active.value !== null && active.value !== i) || undefined}
+                    onClick={() => emit("select", i)}
+                    onMouseenter={() => emit("hover", i)}
+                    onMouseleave={() => emit("hover", null)}
+                    onFocus={() => emit("hover", i)}
+                    onBlur={() => emit("hover", null)}
+                  />
+                ) : null}
+                {props.showValues && s.labelY != null ? (
+                  <text class="hk-bar-chart__value" x={s.centerX} y={s.labelY}>
+                    {props.formatValue(bar.value)}
+                  </text>
+                ) : null}
+                {mark != null ? (
+                  // The slot mark (the supership's Star): a nested <svg>
+                  // wrapper maps the icon's 24-unit glyph box onto a
+                  // 12-unit mark centered on the x-label's optical
+                  // center — positioned HERE so the consumer passes a
+                  // bare lucide component and knows no geometry. Ink
+                  // (currentColor) lives in SCSS.
+                  <svg
+                    class="hk-bar-chart__xmark"
+                    x={s.centerX - BAR_MARK.size / 2}
+                    y={l.baselineY + BAR_MARK.top}
+                    width={BAR_MARK.size}
+                    height={BAR_MARK.size}
+                    viewBox={`0 0 ${BAR_MARK.glyphBox} ${BAR_MARK.glyphBox}`}
+                    aria-hidden="true"
+                  >
+                    {mark}
+                  </svg>
+                ) : (
+                  <text class="hk-bar-chart__x" x={s.centerX} y={l.baselineY + 14}>
+                    {bar.label}
+                  </text>
+                )}
+              </g>
+            );
+          })}
         </svg>
       );
     };

package/src/components/HkTrendChart.test.tsx

@@ -1,6 +1,8 @@
 // Component-side cases for the SVG trend chart (the mirror's render-layer
 // cases, mounted for real through happy-dom). The pure geometry cases live
 // in ./trendGeometry.test.ts, ported from the Rust mirror's cfg(test).
+// The wowsp-migration cases (named guides, dot ink, axis text, yDomain)
+// pin the optional extensions and the byte-identical legacy default.
 //
 // AI-generated (glm-5.3-flash via DeepSeek Harness), 2026-11-03 — SySL-1.0 §2.3.
 
@@ -12,6 +14,7 @@ import { createApp, h, nextTick, ref } from "vue";
 import { afterEach, describe, expect, it } from "vitest";
 
 import HkTrendChart from "./HkTrendChart";
+import { renderTrendChartSvg } from "./trendGeometry";
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
 
@@ -32,6 +35,15 @@ afterEach(() => {
 });
 
 const CPU = { label: "cpu", data: [{ time: 0, value: 1 }, { time: 5000, value: 4 }] };
+/** A [0, 100] series: y(v) = 200 - 1.7v, so tier values land on clean pins. */
+const TIER = { label: "tier", data: [{ time: 0, value: 0 }, { time: 5000, value: 100 }] };
+/** A [62, 78] series: the stepped-domain fixture (a padded PR percentage). */
+const PR = { label: "pr", data: [{ time: 0, value: 62 }, { time: 5000, value: 78 }] };
+/** Three samples: enough for three unclamped x ticks. */
+const TRIPLE = {
+  label: "cpu",
+  data: [{ time: 0, value: 1 }, { time: 2500, value: 2.5 }, { time: 5000, value: 4 }],
+};
 
 describe("HkTrendChart", () => {
   it("renders the mirror's DOM contract on its own contents host", () => {
@@ -140,6 +152,300 @@ describe("HkTrendChart", () => {
     );
   });
 
+  it("keeps the legacy output byte-identical when every new prop is absent", () => {
+    // The exact legacy frame, pinned end to end: no guides, no dots, no
+    // axis text — the mirror's markup, byte for byte.
+    const svg = renderTrendChartSvg([CPU], { now: 5000, timeWindowMs: 5000 });
+    expect(svg).toBe(
+      `<svg class="hk-trend-chart__svg" viewBox="0 0 640 240" preserveAspectRatio="none" style="display:block;width:100%;height:100%">` +
+        `<path class="hk-trend-chart__area" d="M 50 200 L 620 30 L 620 200 L 50 200 Z" fill="rgb(var(--color-primary))" fill-opacity="0.12" stroke="none"/>` +
+        `<polyline class="hk-trend-chart__line" points="50,200 620,30" fill="none" stroke="rgb(var(--color-primary))" stroke-width="2" stroke-linejoin="round" stroke-linecap="round"/>` +
+        `</svg>`,
+    );
+    // The mounted component injects exactly that string — every new prop's
+    // default is a no-op. happy-dom re-serializes SVG self-closing tags, so
+    // the mount is compared against the pinned string parsed through the
+    // same DOM lens (the pure-string equality above already pins the exact
+    // bytes).
+    const el = mount({ pens: [CPU], now: 5000, timeWindowMs: 5000 });
+    const parsed = document.createElement("div");
+    parsed.innerHTML = svg;
+    expect(el.querySelector("svg.hk-trend-chart__svg")!.outerHTML).toBe(
+      parsed.querySelector("svg.hk-trend-chart__svg")!.outerHTML,
+    );
+  });
+
+  it("renders chart-level named guides with labels, color and hint", () => {
+    const el = mount({
+      pens: [TIER],
+      now: 5000,
+      timeWindowMs: 5000,
+      guides: [{ value: 60, label: "S", color: "#00AA00", dash: "2 2", hint: "s-tier" }],
+    });
+    // y(60) on the [0, 100] domain: 200 - 0.6 * 170 = 98.
+    const guide = el.querySelector("line.hk-trend-chart__guide")!;
+    expect(guide).not.toBeNull();
+    expect(guide.getAttribute("x1")).toBe("50");
+    expect(guide.getAttribute("x2")).toBe("620");
+    expect(guide.getAttribute("y1")).toBe("98");
+    expect(guide.getAttribute("y2")).toBe("98");
+    expect(guide.getAttribute("stroke")).toBe("#00AA00");
+    expect(guide.getAttribute("stroke-width")).toBe("1");
+    expect(guide.getAttribute("stroke-dasharray")).toBe("2 2");
+    expect(guide.getAttribute("data-hint")).toBe("s-tier");
+    expect(guide.hasAttribute("stroke-opacity")).toBe(false);
+    // The tier label sits inside the plot near the left edge, one step
+    // above its line, in the guide's color.
+    const label = el.querySelector("text.hk-trend-chart__guide-label")!;
+    expect(label.textContent).toBe("S");
+    expect(label.getAttribute("x")).toBe("56");
+    expect(label.getAttribute("y")).toBe("94");
+    expect(label.getAttribute("fill")).toBe("#00AA00");
+    expect(label.getAttribute("font-size")).toBe("10");
+    expect(label.getAttribute("text-anchor")).toBe("start");
+
+    // Defaults: a quiet currentColor line with the alarm dashed flavor,
+    // no label, no hint.
+    const quiet = mount({ pens: [TIER], now: 5000, timeWindowMs: 5000, guides: [{ value: 40 }] });
+    const line = quiet.querySelector("line.hk-trend-chart__guide")!;
+    expect(line.getAttribute("y1")).toBe("132");
+    expect(line.getAttribute("stroke")).toBe("currentColor");
+    expect(line.getAttribute("stroke-opacity")).toBe("0.35");
+    expect(line.getAttribute("stroke-dasharray")).toBe("6 4");
+    expect(line.hasAttribute("data-hint")).toBe(false);
+    expect(quiet.querySelectorAll("text.hk-trend-chart__guide-label")).toHaveLength(0);
+
+    // Out-of-range guides clip like the alarm lines, labels included.
+    const clipped = mount({
+      pens: [TIER],
+      now: 5000,
+      timeWindowMs: 5000,
+      guides: [{ value: 150, label: "ghost" }, { value: -20 }],
+    });
+    expect(clipped.querySelectorAll("line.hk-trend-chart__guide")).toHaveLength(0);
+    expect(clipped.querySelectorAll("text.hk-trend-chart__guide-label")).toHaveLength(0);
+  });
+
+  it("draws per-sample dots with tier ink and hints", () => {
+    const el = mount({
+      pens: [
+        {
+          label: "cpu",
+          data: [
+            { time: 0, value: 1, fill: "#00FF88" },
+            { time: 2500, value: 2.5, fill: "#FF1744", hint: "spike" },
+            { time: 5000, value: 4 },
+          ],
+        },
+      ],
+      now: 5000,
+      timeWindowMs: 5000,
+    });
+    const dots = el.querySelectorAll("circle.hk-trend-chart__dot");
+    expect(dots).toHaveLength(2);
+    expect(dots[0].getAttribute("cx")).toBe("50");
+    expect(dots[0].getAttribute("cy")).toBe("200");
+    expect(dots[0].getAttribute("r")).toBe("3.5");
+    expect(dots[0].getAttribute("fill")).toBe("#00FF88");
+    expect(dots[0].hasAttribute("data-hint")).toBe(false);
+    expect(dots[1].getAttribute("cx")).toBe("335");
+    expect(dots[1].getAttribute("cy")).toBe("115");
+    expect(dots[1].getAttribute("fill")).toBe("#FF1744");
+    expect(dots[1].getAttribute("data-hint")).toBe("spike");
+    // Untagged samples stay dot-free.
+    const bare = mount({ pens: [CPU], now: 5000, timeWindowMs: 5000 });
+    expect(bare.querySelectorAll("circle.hk-trend-chart__dot")).toHaveLength(0);
+  });
+
+  it("renders y-axis numbers and applies the guide clearance rule", () => {
+    const fmt = (value: number) => value.toFixed(1);
+    const el = mount({ pens: [CPU], now: 5000, timeWindowMs: 5000, yAxisFormat: fmt });
+    // Floor / mid / ceiling of the shown [1, 4] domain, in the left grid
+    // gutter, right-anchored at plotLeft - 6.
+    const ticks = el.querySelectorAll("text.hk-trend-chart__y-tick");
+    expect(ticks).toHaveLength(3);
+    expect(ticks[0].getAttribute("x")).toBe("44");
+    expect(ticks[0].getAttribute("y")).toBe("203");
+    expect(ticks[0].getAttribute("text-anchor")).toBe("end");
+    expect(ticks[0].getAttribute("font-size")).toBe("10");
+    expect(ticks[0].textContent).toBe("1.0");
+    expect(ticks[1].getAttribute("y")).toBe("118");
+    expect(ticks[1].textContent).toBe("2.5");
+    expect(ticks[2].getAttribute("y")).toBe("33");
+    expect(ticks[2].textContent).toBe("4.0");
+
+    // The floor number always renders; mid/ceiling drop when their
+    // gridline sits within yAxisClearancePx of a guide's line. Guide at
+    // 2.5 → y 115 (mid), guide at 4 → y 30 (ceiling).
+    const dropped = mount({
+      pens: [CPU],
+      now: 5000,
+      timeWindowMs: 5000,
+      yAxisFormat: fmt,
+      yAxisClearancePx: 9,
+      guides: [{ value: 2.5 }, { value: 4 }],
+    });
+    const kept = dropped.querySelectorAll("text.hk-trend-chart__y-tick");
+    expect(kept).toHaveLength(1);
+    expect(kept[0].textContent).toBe("1.0");
+    // The guides themselves are untouched by the clearance rule.
+    expect(dropped.querySelectorAll("line.hk-trend-chart__guide")).toHaveLength(2);
+
+    // Default clearance is 0: even a coincident guide drops nothing.
+    const defaultClearance = mount({
+      pens: [CPU],
+      now: 5000,
+      timeWindowMs: 5000,
+      yAxisFormat: fmt,
+      guides: [{ value: 2.5 }],
+    });
+    expect(defaultClearance.querySelectorAll("text.hk-trend-chart__y-tick")).toHaveLength(3);
+  });
+
+  it("renders baseline x ticks when both count and format are given", () => {
+    const at = (timeMs: number) => `@${timeMs}`;
+    const el = mount({
+      pens: [TRIPLE],
+      now: 5000,
+      timeWindowMs: 5000,
+      xTickCount: 3,
+      xTickFormat: at,
+    });
+    // Three evenly spaced ticks across the shown data's [0, 5000] span,
+    // under the baseline (plotBottom + 14).
+    const ticks = el.querySelectorAll("text.hk-trend-chart__x-tick");
+    expect(ticks).toHaveLength(3);
+    expect(ticks[0].getAttribute("x")).toBe("50");
+    expect(ticks[0].getAttribute("y")).toBe("214");
+    expect(ticks[0].getAttribute("text-anchor")).toBe("middle");
+    expect(ticks[0].textContent).toBe("@0");
+    expect(ticks[1].getAttribute("x")).toBe("335");
+    expect(ticks[1].textContent).toBe("@2500");
+    expect(ticks[2].getAttribute("x")).toBe("620");
+    expect(ticks[2].textContent).toBe("@5000");
+
+    // The count clamps to the shown sample count.
+    const clamped = mount({
+      pens: [CPU],
+      now: 5000,
+      timeWindowMs: 5000,
+      xTickCount: 5,
+      xTickFormat: at,
+    });
+    const two = clamped.querySelectorAll("text.hk-trend-chart__x-tick");
+    expect(two).toHaveLength(2);
+    expect(two[0].textContent).toBe("@0");
+    expect(two[1].textContent).toBe("@5000");
+
+    // Half the pair means no ticks at all.
+    const onlyCount = mount({ pens: [CPU], xTickCount: 3 });
+    const onlyFormat = mount({ pens: [CPU], xTickFormat: at });
+    expect(onlyCount.querySelectorAll("text.hk-trend-chart__x-tick")).toHaveLength(0);
+    expect(onlyFormat.querySelectorAll("text.hk-trend-chart__x-tick")).toHaveLength(0);
+  });
+
+  it("steps the y domain with yDomain (pad / minSpan / floorAtZero)", () => {
+    // Absent: today's raw extent [62, 78].
+    const raw = mount({ pens: [PR], now: 5000, timeWindowMs: 5000 });
+    expect(raw.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,200 620,30",
+    );
+
+    // padToMultiple + floorAtZero: span 16 → padded to 20 → the floor
+    // anchors at zero and the elevated ceiling re-pads → [0, 80].
+    const stepped = mount({
+      pens: [PR],
+      now: 5000,
+      timeWindowMs: 5000,
+      yDomain: { padToMultiple: 10, floorAtZero: true },
+    });
+    expect(stepped.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,68.25 620,34.25",
+    );
+
+    // padToMultiple alone pads the span up from the raw floor: [62, 82].
+    const padded = mount({
+      pens: [PR],
+      now: 5000,
+      timeWindowMs: 5000,
+      yDomain: { padToMultiple: 10 },
+    });
+    expect(padded.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,200 620,64",
+    );
+
+    // minSpan widens a narrow extent: [62, 102] — read back through the
+    // y-axis numbers so the domain pins without float needles.
+    const widened = mount({
+      pens: [PR],
+      now: 5000,
+      timeWindowMs: 5000,
+      yDomain: { minSpan: 40 },
+      yAxisFormat: (value: number) => String(value),
+    });
+    expect(widened.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,200 620,132",
+    );
+    const widenedTicks = widened.querySelectorAll("text.hk-trend-chart__y-tick");
+    expect(widenedTicks).toHaveLength(3);
+    expect(widenedTicks[0].textContent).toBe("62");
+    expect(widenedTicks[1].textContent).toBe("82");
+    expect(widenedTicks[2].textContent).toBe("102");
+
+    // floorAtZero alone anchors at zero and keeps the raw ceiling: [0, 78].
+    const floored = mount({
+      pens: [PR],
+      now: 5000,
+      timeWindowMs: 5000,
+      yDomain: { floorAtZero: true },
+      yAxisFormat: (value: number) => String(value),
+    });
+    const flooredTicks = floored.querySelectorAll("text.hk-trend-chart__y-tick");
+    expect(flooredTicks).toHaveLength(3);
+    expect(flooredTicks[0].textContent).toBe("0");
+    expect(flooredTicks[1].textContent).toBe("39");
+    expect(flooredTicks[2].textContent).toBe("78");
+
+    // A flat series under a stepped domain pads up to one step instead of
+    // the flat ±1: [0, 10] keeps the line mid-plot.
+    const flat = mount({
+      pens: [{ label: "cpu", data: [{ time: 0, value: 5 }, { time: 5000, value: 5 }] }],
+      now: 5000,
+      timeWindowMs: 5000,
+      yDomain: { padToMultiple: 10, floorAtZero: true },
+    });
+    expect(flat.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,115 620,115",
+    );
+  });
+
+  it("passes preserveAspectRatio through (the default stays none)", () => {
+    const meet = mount({ pens: [CPU], preserveAspectRatio: "xMidYMid meet" });
+    expect(
+      meet.querySelector("svg.hk-trend-chart__svg")!.getAttribute("preserveAspectRatio"),
+    ).toBe("xMidYMid meet");
+    const stretch = mount({ pens: [CPU] });
+    expect(
+      stretch.querySelector("svg.hk-trend-chart__svg")!.getAttribute("preserveAspectRatio"),
+    ).toBe("none");
+  });
+
+  it("escapes the consumer strings the new props render into the SVG", () => {
+    const svg = renderTrendChartSvg([TIER], {
+      now: 5000,
+      timeWindowMs: 5000,
+      guides: [{ value: 60, label: `<b class="x">&</b>`, hint: `"q"` }],
+      yAxisFormat: (value: number) => `<${value}>`,
+      xTickCount: 1,
+      xTickFormat: (timeMs: number) => "t&t",
+    });
+    expect(svg).not.toContain(`<b class="x">`);
+    expect(svg).toContain("&lt;b class=&quot;x&quot;&gt;&amp;&lt;/b&gt;");
+    expect(svg).toContain(`data-hint="&quot;q&quot;"`);
+    expect(svg).toContain("&lt;0&gt;");
+    expect(svg).toContain("t&amp;t");
+  });
+
   it("stays dependency-free (no echarts import, no echarts dep)", () => {
     // The old build lazily imported echarts/core; the rewrite must not let
     // it back in — pinned at the source and manifest level, the same way
@@ -160,4 +466,4 @@ describe("HkTrendChart", () => {
     ) as { dependencies?: Record<string, string> };
     expect(Object.keys(pkg.dependencies ?? {})).not.toContain("echarts");
   });
-});
+});

package/src/components/HkTrendChart.tsx

@@ -1,11 +1,20 @@
 import { computed, defineComponent, type PropType } from "vue";
 
-import { renderTrendChartSvg, trendHeightPx, type AlarmThresholds, type TrendPen, type TrendPoint } from "./trendGeometry";
+import {
+  renderTrendChartSvg,
+  trendHeightPx,
+  type AlarmThresholds,
+  type TrendGuide,
+  type TrendPen,
+  type TrendPoint,
+  type TrendYDomain,
+} from "./trendGeometry";
 
 // The pen/threshold data types live in the pure geometry module (the Rust
 // mirror's trend_chart.rs surface) and re-export here so direct-file
-// importers keep their established paths.
-export type { AlarmThresholds, TrendPen, TrendPoint };
+// importers keep their established paths. TrendGuide / TrendYDomain are the
+// wowsp-migration extensions (documented in ./trendGeometry).
+export type { AlarmThresholds, TrendGuide, TrendPen, TrendPoint, TrendYDomain };
 
 /**
  * HkTrendChart — labelled time-series ("pens") drawn over a rolling time
@@ -22,9 +31,13 @@ export type { AlarmThresholds, TrendPen, TrendPoint };
  *   div.hk-trend-chart  style="width:100%;height:{height}"
  *     div[style="display:contents"]
  *       svg.hk-trend-chart__svg  viewBox + preserveAspectRatio="none"
- *         line.hk-trend-chart__threshold  (one per present limit)
- *         path.hk-trend-chart__area       (one per pen)
- *         polyline.hk-trend-chart__line   (one per pen)
+ *         line.hk-trend-chart__guide       (optional chart-level guides)
+ *         line.hk-trend-chart__threshold   (one per present limit)
+ *         text.hk-trend-chart__y-tick / __x-tick  (optional axis text)
+ *         path.hk-trend-chart__area        (one per pen)
+ *         polyline.hk-trend-chart__line    (one per pen)
+ *         circle.hk-trend-chart__dot       (optional, per inked sample)
+ *         text.hk-trend-chart__guide-label (optional tier names, on top)
  *
  * The `hk-trend-chart*` classes are INERT hooks (no sheet defines them);
  * the component ships NO stylesheet and no canvas. Pen ink rides the theme
@@ -32,6 +45,15 @@ export type { AlarmThresholds, TrendPen, TrendPoint };
  * a re-render, and threshold guides keep the old markLine colors and dash
  * flavors.
  *
+ * WOWSP-MIGRATION EXTRAS (all optional, all defaulting to today's frame):
+ * chart-level named `guides` (dashed tier lines with left-edge tier labels
+ * and hints), per-sample dot ink (`TrendPoint.fill`/`hint`), y-axis
+ * numbers (`yAxisFormat` plus the `yAxisClearancePx` collision rule),
+ * baseline x ticks (`xTickCount` + `xTickFormat`), a stepped `yDomain`,
+ * and a `preserveAspectRatio` override. The exact rules live in
+ * ./trendGeometry; with the extras absent the markup is byte-identical to
+ * the mirror's.
+ *
  * OFFLINE PRE-RENDER SEMANTICS: no animation exists at all — the first
  * render IS the finished frame. Streaming updates re-render the same
  * geometry synchronously when `pens` is reactive state. The identical
@@ -63,6 +85,29 @@ export default defineComponent({
     now: { type: Number, default: undefined },
     /** The viewBox width (default 640 — the mirror's frame). */
     width: { type: Number, default: 640 },
+    /** Chart-level horizontal guides rendered with the alarms — the named
+     * tier lines. Default: none. */
+    guides: { type: Array as PropType<TrendGuide[]>, default: undefined },
+    /** Formats the y-axis gridline numbers (floor/mid/ceiling of the shown
+     * domain); absent → no y-axis text. */
+    yAxisFormat: { type: Function as PropType<(value: number) => string>, default: undefined },
+    /** A mid/ceiling number whose gridline sits within this many viewBox px
+     * of a guide's line is dropped (the floor number always renders).
+     * Default 0 — nothing is dropped. */
+    yAxisClearancePx: { type: Number, default: 0 },
+    /** Baseline tick count, clamped to the shown sample count; needs
+     * `xTickFormat`. Default: no x ticks. */
+    xTickCount: { type: Number, default: undefined },
+    /** Formats each tick's epoch ms; needs `xTickCount`. */
+    xTickFormat: { type: Function as PropType<(timeMs: number) => string>, default: undefined },
+    /** The stepped y extent rule; absent → the raw extent (flat-pad ±1). */
+    yDomain: { type: Object as PropType<TrendYDomain>, default: undefined },
+    /** The SVG fit (default "none" — stretch to the box, the mirror's
+     * rule; "xMidYMid meet" keeps the frame's aspect). */
+    preserveAspectRatio: {
+      type: String as PropType<"none" | "xMidYMid meet">,
+      default: "none",
+    },
   },
   setup(props) {
     const svg = computed(() =>
@@ -72,6 +117,13 @@ export default defineComponent({
         width: props.width,
         height: props.height,
         showThresholds: props.showThresholds,
+        guides: props.guides,
+        yAxisFormat: props.yAxisFormat,
+        yAxisClearancePx: props.yAxisClearancePx,
+        xTickCount: props.xTickCount,
+        xTickFormat: props.xTickFormat,
+        yDomain: props.yDomain,
+        preserveAspectRatio: props.preserveAspectRatio,
       }),
     );
     // An empty height keeps the viewBox-derived px (the mirror's rule).

package/src/components/barChart.ts

@@ -7,7 +7,10 @@
 // the two apps draw the identical bar shape: equal slots, each bar
 // centered with 62%-of-slot width capped at 36px, top-only corner
 // rounding clamped so a squat bar never inverts its corners, and three
-// gridline guides (0 / half / the nice max).
+// gridline guides (0 / half / the nice max). Each slot also carries the
+// baseline for an optional value label above the bar (top − 5, null for
+// an empty slot) — the wowsp tier histogram's labelY convention, which
+// HkBarChart renders behind its showValues prop.
 //
 // AI-generated (GLM-5.3 via ZCode), 2026-10-31 — SySL-1.0 §2.3.
 
@@ -18,6 +21,12 @@ export interface BarSlot {
   /** Empty string for a zero bucket — no invisible sliver to hover. */
   path: string;
   value: number;
+  /** Text baseline for a value label ABOVE the bar (top − 5, wowsp's
+   * tierBars convention — the 10-unit label clears the bar with a
+   * readable gap); null for a zero bucket, so an empty slot carries no
+   * above-bar label either (HkBarChart's showValues renders labelY
+   * non-null slots only). */
+  labelY: number | null;
 }
 
 /** The full layout HkBarChart renders. */
@@ -79,7 +88,7 @@ export function barLayout(
   const bars: BarSlot[] = values.map((value, i) => {
     const centerX = sidePad + slotW * (i + 0.5);
     if (!(value > 0)) {
-      return { centerX, barWidth: barW, path: "", value };
+      return { centerX, barWidth: barW, path: "", value, labelY: null };
     }
     const h = (value / scale) * plotH;
     const top = baselineY - h;
@@ -94,7 +103,7 @@ export function barLayout(
       `L ${fmtBar(x1 - rx)} ${fmtBar(top)} ` +
       `Q ${fmtBar(x1)} ${fmtBar(top)} ${fmtBar(x1)} ${fmtBar(top + rx)} ` +
       `L ${fmtBar(x1)} ${fmtBar(baselineY)} Z`;
-    return { centerX, barWidth: barW, path, value };
+    return { centerX, barWidth: barW, path, value, labelY: fmtBar(top - 5) };
   });
   const gridlines = [0, 0.5, 1].map((f) => ({
     y: fmtBar(baselineY - f * plotH),

package/src/components/trendGeometry.ts

@@ -10,12 +10,20 @@
 // contract the render layer mounts and the delta history against the old
 // echarts build.
 //
+// WOWSP-MIGRATION SUPERSET: HkTrendChart grew optional capabilities for
+// wowsp's PrTrendChart — chart-level named guides, per-sample dot ink,
+// y-axis numbers with a clearance rule, baseline x ticks, a stepped yDomain
+// and a preserveAspectRatio override. Every extension is optional and absent
+// means the mirror's exact math and markup (the ported cfg(test) cases stay
+// verbatim); the extra types live TS-side until the mirror grows them.
+//
 // Dependency-free (no Vue, no chart library): everything here is pure and
 // unit-testable. `renderTrendChartSvg` is the OFFLINE pre-render entry — its
 // string is the finished frame (nothing animates, anywhere), and consumers
 // embed it directly (inline or as a data URL; html-to-image and static
-// exports just work). Pen labels are not rendered into the markup, so no
-// consumer-authored string reaches the SVG and nothing needs escaping.
+// exports just work). Pen labels are still not rendered into the markup; the
+// superset's consumer strings (guide labels/hints, dot ink, formatted axis
+// text) go through `escapeSvgText` before they enter the SVG.
 //
 // AI-generated (glm-5.3-flash via DeepSeek Harness), 2026-11-03 — SySL-1.0 §2.3.
 
@@ -42,16 +50,40 @@ export const TREND_THRESHOLD_LL_COLOR = "#FF1744";
 export const TREND_THRESHOLD_DASHED = "6 4";
 export const TREND_THRESHOLD_DOTTED = "1 3";
 
+/** Chart-level guide defaults: a quiet `currentColor` line (consumers name
+ * tier colors) with the alarm `dashed` flavor. */
+export const TREND_GUIDE_DEFAULT_COLOR = "currentColor";
+export const TREND_GUIDE_DEFAULT_DASH = TREND_THRESHOLD_DASHED;
+export const TREND_GUIDE_DEFAULT_OPACITY = 0.35;
+/** A named guide's label sits inside the plot near the left edge, a step
+ * above its line (viewBox px). */
+export const TREND_GUIDE_LABEL_INSET = 6;
+export const TREND_GUIDE_LABEL_LIFT = 4;
+/** Axis text: one small size; y numbers sit in the left grid gutter, x ticks
+ * drop under the baseline (viewBox px). */
+export const TREND_CHART_AXIS_FONT_SIZE = 10;
+export const TREND_Y_TICK_INSET = 6;
+export const TREND_Y_TICK_BASELINE_SHIFT = 3;
+export const TREND_X_TICK_DROP = 14;
+/** Per-sample dot radius (viewBox px). */
+export const TREND_CHART_DOT_RADIUS = 3.5;
+
 /** The y axis collapses when every shown value is equal; the range pads by
  * this much on each side so the line lands mid-plot. */
 const TREND_FLAT_RANGE_PAD = 1;
 const TREND_RANGE_EPSILON = 1e-9;
 
-/** One sample (the old echarts option tree's `[time, value]` entries). */
+/** One sample (the old echarts option tree's `[time, value]` entries). The
+ * wowsp migration adds per-sample dot ink: a sample that names `fill`
+ * renders a dot at its coordinate, optionally carrying a `hint`. */
 export interface TrendPoint {
   /** Epoch milliseconds. */
   time: number;
   value: number;
+  /** Dot ink; a dot is drawn at the sample only when present. */
+  fill?: string;
+  /** The dot's data-hint payload; rendered only alongside `fill`. */
+  hint?: string;
 }
 
 /** Per-pen alarm limits. */
@@ -62,6 +94,35 @@ export interface AlarmThresholds {
   ll?: number;
 }
 
+/** One chart-level horizontal guide (the wowsp tier chart's named tier
+ * lines). Clipped to the shown y range like the alarm thresholds. */
+export interface TrendGuide {
+  /** The value the line sits at. */
+  value: number;
+  /** Tier name rendered as text inside the plot near the left edge. */
+  label?: string;
+  /** Line/label ink; default a quiet `currentColor`. */
+  color?: string;
+  /** Dash array; default `"6 4"` (the alarm `dashed` flavor). */
+  dash?: string;
+  /** The line's data-hint payload. */
+  hint?: string;
+}
+
+/** The stepped y extent rule (absent → the raw extent with the flat pad).
+ * The span widens to `minSpan`, is padded UP to the next `padToMultiple`,
+ * and `floorAtZero` anchors the floor at 0 when the shown extent is
+ * non-negative (re-padding the elevated ceiling so the top lands on a step
+ * and no shown sample escapes the domain). */
+export interface TrendYDomain {
+  /** Pad the extent's span UP to the next multiple of this. */
+  padToMultiple?: number;
+  /** Never show a span narrower than this (value units). */
+  minSpan?: number;
+  /** Anchor the floor at 0 when the shown extent is non-negative. */
+  floorAtZero?: boolean;
+}
+
 /** One labelled series. */
 export interface TrendPen {
   label: string;
@@ -92,6 +153,14 @@ export interface TrendFrame {
   valueMax: number;
 }
 
+/** One projected per-sample dot. */
+export interface TrendDot {
+  x: number;
+  y: number;
+  fill: string;
+  hint?: string;
+}
+
 /** One pen's projected geometry. */
 export interface TrendPenGeometry {
   label: string;
@@ -101,6 +170,8 @@ export interface TrendPenGeometry {
   line: string;
   /** The area `d` attribute (the line closed down to the baseline). */
   area: string;
+  /** Per-sample dots in draw order (the samples naming `fill`). */
+  dots: TrendDot[];
 }
 
 /** One horizontal alarm guide (one old `markLine` entry). */
@@ -111,11 +182,61 @@ export interface TrendThresholdLine {
   dash: string;
 }
 
+/** One projected chart-level guide. */
+export interface TrendGuideLine {
+  value: number;
+  y: number;
+  /** Resolved ink (`TREND_GUIDE_DEFAULT_COLOR` when unnamed). */
+  color: string;
+  dash: string;
+  /** `stroke-opacity`; set only for the default color's quiet line. */
+  opacity?: number;
+  hint?: string;
+  label?: string;
+  labelX: number;
+  labelY: number;
+}
+
+/** One y-axis gridline number (floor/mid/ceiling of the shown domain). */
+export interface TrendYTick {
+  value: number;
+  /** The text's baseline y (the gridline y shifted for optical centering). */
+  y: number;
+  text: string;
+}
+
+/** One baseline x tick. */
+export interface TrendXTick {
+  /** The tick's time (interpolated across the shown data's time span). */
+  time: number;
+  x: number;
+  y: number;
+  text: string;
+}
+
 /** Everything the render layer needs. */
 export interface TrendGeometry {
   frame: TrendFrame;
   pens: TrendPenGeometry[];
   thresholds: TrendThresholdLine[];
+  /** Chart-level named guides (empty without the `guides` extra). */
+  guides: TrendGuideLine[];
+  /** Gridline numbers (empty without `yAxisFormat`). */
+  yTicks: TrendYTick[];
+  /** Baseline ticks (empty without `xTickCount` + `xTickFormat`). */
+  xTicks: TrendXTick[];
+}
+
+/** The wowsp-migration extensions, passed to `trendGeometry` after the
+ * mirror's six pinned arguments. Every field is optional; absent means the
+ * mirror's exact behavior. */
+export interface TrendGeometryExtras {
+  guides?: readonly TrendGuide[];
+  yDomain?: TrendYDomain;
+  yAxisFormat?: (value: number) => string;
+  yAxisClearancePx?: number;
+  xTickCount?: number;
+  xTickFormat?: (timeMs: number) => string;
 }
 
 /**
@@ -195,9 +316,67 @@ export function trendAreaPath(points: readonly TrendCoord[], baselineY: number):
   return path;
 }
 
+/** The next multiple of `step` at or above `span` (a zero span pads up to
+ * one step; sub-epsilon float noise does not trigger an extra step). */
+function padUpToMultiple(span: number, step: number): number {
+  const stepped = Math.ceil((span - TREND_RANGE_EPSILON) / step) * step;
+  return stepped > 0 ? stepped : step;
+}
+
+/** A usable `padToMultiple`: finite and positive. */
+function isUsableStep(value: number | undefined): value is number {
+  return value !== undefined && Number.isFinite(value) && value > 0;
+}
+
+/**
+ * The `yDomain` extent rule (the wowsp tier chart's stepped axis): the raw
+ * span widens to `minSpan`, is padded UP to the next `padToMultiple`, and
+ * `floorAtZero` anchors the floor at 0 when the shown extent is
+ * non-negative — re-padding the elevated ceiling so the top lands on a step
+ * and no shown sample escapes the domain. Negative extents keep their floor
+ * (zero-anchoring would hide the data) and only widen by the span.
+ */
+function applyTrendYDomain(
+  rawMin: number,
+  rawMax: number,
+  domain: TrendYDomain,
+): { min: number; max: number } {
+  const rawSpan = rawMax - rawMin;
+  const minSpan = domain.minSpan;
+  let span =
+    minSpan !== undefined && Number.isFinite(minSpan) && minSpan >= 0
+      ? Math.max(rawSpan, minSpan)
+      : rawSpan;
+  if (isUsableStep(domain.padToMultiple)) span = padUpToMultiple(span, domain.padToMultiple);
+  if (domain.floorAtZero === true && rawMin >= 0) {
+    const ceiling = isUsableStep(domain.padToMultiple)
+      ? padUpToMultiple(rawMax, domain.padToMultiple)
+      : Math.max(rawMax, rawMin + span);
+    return { min: 0, max: ceiling };
+  }
+  return { min: rawMin, max: rawMin + span };
+}
+
+/**
+ * XML-escape a consumer-authored string before it enters the SVG markup
+ * (guide labels/hints, dot ink, formatted axis text). Attribute values and
+ * text content share one escape — the extra entities are valid in both
+ * positions, so there is no second code path to forget.
+ */
+function escapeSvgText(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
 /**
- * Pens → projected geometry. Pure: same pens + clock + window + frame →
- * the same geometry.
+ * Pens → projected geometry. Pure: same pens + clock + window + frame +
+ * extras → the same geometry. The first six arguments are the mirror's
+ * pinned surface; `extras` carries the wowsp-migration extensions and
+ * defaults to the mirror's exact behavior.
  */
 export function trendGeometry(
   pens: readonly TrendPen[],
@@ -206,6 +385,7 @@ export function trendGeometry(
   width: number,
   height: number,
   showThresholds: boolean,
+  extras: TrendGeometryExtras = {},
 ): TrendGeometry {
   const windowEnd = trendWindowEnd(pens, now);
   const windowSpan = Math.max(timeWindowMs, 0);
@@ -225,9 +405,11 @@ export function trendGeometry(
   // fits the data extent and a threshold value does not extend the axis.
   let valueMin = Infinity;
   let valueMax = -Infinity;
+  const shownTimes: number[] = [];
   for (const pen of pens) {
     for (const point of pen.data) {
       if (point.time >= windowStart && point.time <= windowEnd) {
+        shownTimes.push(point.time);
         if (point.value < valueMin) valueMin = point.value;
         if (point.value > valueMax) valueMax = point.value;
       }
@@ -237,6 +419,13 @@ export function trendGeometry(
     valueMin = 0;
     valueMax = 1;
   }
+  // The stepped-domain extra (absent → the raw extent below, the mirror's
+  // rule). The trailing flat-pad still catches a degenerate result.
+  if (extras.yDomain !== undefined) {
+    const stepped = applyTrendYDomain(valueMin, valueMax, extras.yDomain);
+    valueMin = stepped.min;
+    valueMax = stepped.max;
+  }
   if (valueMax - valueMin < TREND_RANGE_EPSILON) {
     // A flat (or single-sample) series collapses the axis; pad it so the
     // line lands mid-plot instead of dividing by zero.
@@ -252,9 +441,15 @@ export function trendGeometry(
   for (let index = 0; index < pens.length; index += 1) {
     const pen = pens[index];
     const points: TrendCoord[] = [];
+    const dots: TrendDot[] = [];
     for (const point of pen.data) {
       if (point.time >= windowStart && point.time <= windowEnd) {
-        points.push({ x: xOf(point.time), y: yOf(point.value) });
+        const coord = { x: xOf(point.time), y: yOf(point.value) };
+        points.push(coord);
+        // A sample carries a dot only when it names its own ink.
+        if (point.fill !== undefined) {
+          dots.push({ x: coord.x, y: coord.y, fill: point.fill, hint: point.hint });
+        }
       }
     }
     projected.push({
@@ -263,6 +458,7 @@ export function trendGeometry(
       line: trendPolyline(points),
       area: trendAreaPath(points, plotBottom),
       points,
+      dots,
     });
   }
 
@@ -287,6 +483,81 @@ export function trendGeometry(
     }
   }
 
+  const guides: TrendGuideLine[] = [];
+  for (const guide of extras.guides ?? []) {
+    // The alarm guides clip outside the axis range; the named guides — and
+    // their labels with them — clip the same way.
+    if (guide.value < valueMin || guide.value > valueMax) continue;
+    const y = yOf(guide.value);
+    guides.push({
+      value: guide.value,
+      y,
+      color: guide.color ?? TREND_GUIDE_DEFAULT_COLOR,
+      dash: guide.dash ?? TREND_GUIDE_DEFAULT_DASH,
+      // The default ink stays quiet; a named color draws at full strength.
+      opacity: guide.color === undefined ? TREND_GUIDE_DEFAULT_OPACITY : undefined,
+      hint: guide.hint,
+      label: guide.label,
+      labelX: plotLeft + TREND_GUIDE_LABEL_INSET,
+      labelY: y - TREND_GUIDE_LABEL_LIFT,
+    });
+  }
+
+  const yTicks: TrendYTick[] = [];
+  if (extras.yAxisFormat !== undefined) {
+    // Gridline numbers: floor / mid / ceiling of the shown domain. A
+    // mid/ceiling number whose gridline sits within `yAxisClearancePx` of a
+    // rendered guide's line is dropped (the floor number always renders);
+    // viewBox px, like the clearance prop says.
+    const guideYs = guides.map((guide) => guide.y);
+    const clearance = extras.yAxisClearancePx ?? 0;
+    const collides = (y: number): boolean =>
+      clearance > 0 && guideYs.some((guideY) => Math.abs(guideY - y) <= clearance);
+    const mid = valueMin + valueSpan / 2;
+    yTicks.push({
+      value: valueMin,
+      y: yOf(valueMin) + TREND_Y_TICK_BASELINE_SHIFT,
+      text: extras.yAxisFormat(valueMin),
+    });
+    const midY = yOf(mid);
+    if (!collides(midY)) {
+      yTicks.push({ value: mid, y: midY + TREND_Y_TICK_BASELINE_SHIFT, text: extras.yAxisFormat(mid) });
+    }
+    const ceilingY = yOf(valueMax);
+    if (!collides(ceilingY)) {
+      yTicks.push({
+        value: valueMax,
+        y: ceilingY + TREND_Y_TICK_BASELINE_SHIFT,
+        text: extras.yAxisFormat(valueMax),
+      });
+    }
+  }
+
+  const xTicks: TrendXTick[] = [];
+  if (extras.xTickFormat !== undefined && extras.xTickCount !== undefined) {
+    // Evenly spaced ticks across the SHOWN data's time span; the count
+    // clamps to the sample count (a lone tick sits at the span's start).
+    const count = Math.min(Math.max(0, Math.floor(extras.xTickCount)), shownTimes.length);
+    let timeMin = Infinity;
+    let timeMax = -Infinity;
+    for (const time of shownTimes) {
+      if (time < timeMin) timeMin = time;
+      if (time > timeMax) timeMax = time;
+    }
+    if (count >= 1 && Number.isFinite(timeMin)) {
+      for (let index = 0; index < count; index += 1) {
+        const time =
+          count === 1 ? timeMin : timeMin + ((timeMax - timeMin) * index) / (count - 1);
+        xTicks.push({
+          time,
+          x: xOf(time),
+          y: plotBottom + TREND_X_TICK_DROP,
+          text: extras.xTickFormat(time),
+        });
+      }
+    }
+  }
+
   return {
     frame: {
       width,
@@ -302,20 +573,34 @@ export function trendGeometry(
     },
     pens: projected,
     thresholds,
+    guides,
+    yTicks,
+    xTicks,
   };
 }
 
 /**
- * The chart SVG markup: threshold guides first, then each pen's area + line.
- * Byte-for-byte the Rust mirror's `trend_chart_svg` (private there; the
- * public offline entry below wraps it).
+ * The chart SVG markup: named guides, then the threshold guides, then the
+ * axis text, then each pen's area + line + dots, and the named guides'
+ * labels on top. With every wowsp extension absent this is byte-for-byte the
+ * Rust mirror's `trend_chart_svg` (private there; the public offline entry
+ * below wraps it).
  */
-function trendChartSvg(geometry: TrendGeometry): string {
+function trendChartSvg(geometry: TrendGeometry, preserveAspectRatio: string): string {
   const frame = geometry.frame;
-  let svg = `<svg class="hk-trend-chart__svg" viewBox="0 0 ${frame.width} ${frame.height}" preserveAspectRatio="none" style="display:block;width:100%;height:100%">`;
+  let svg = `<svg class="hk-trend-chart__svg" viewBox="0 0 ${frame.width} ${frame.height}" preserveAspectRatio="${preserveAspectRatio}" style="display:block;width:100%;height:100%">`;
+  for (const guide of geometry.guides) {
+    svg += `<line class="hk-trend-chart__guide" x1="${frame.plotLeft}" y1="${guide.y}" x2="${frame.plotRight}" y2="${guide.y}" stroke="${escapeSvgText(guide.color)}"${guide.opacity !== undefined ? ` stroke-opacity="${guide.opacity}"` : ""} stroke-width="1" stroke-dasharray="${escapeSvgText(guide.dash)}"${guide.hint !== undefined ? ` data-hint="${escapeSvgText(guide.hint)}"` : ""}/>`;
+  }
   for (const threshold of geometry.thresholds) {
     svg += `<line class="hk-trend-chart__threshold" x1="${frame.plotLeft}" y1="${threshold.y}" x2="${frame.plotRight}" y2="${threshold.y}" stroke="${threshold.color}" stroke-width="1" stroke-dasharray="${threshold.dash}"/>`;
   }
+  for (const tick of geometry.yTicks) {
+    svg += `<text class="hk-trend-chart__y-tick" x="${frame.plotLeft - TREND_Y_TICK_INSET}" y="${tick.y}" fill="currentColor" font-size="${TREND_CHART_AXIS_FONT_SIZE}" text-anchor="end">${escapeSvgText(tick.text)}</text>`;
+  }
+  for (const tick of geometry.xTicks) {
+    svg += `<text class="hk-trend-chart__x-tick" x="${tick.x}" y="${tick.y}" fill="currentColor" font-size="${TREND_CHART_AXIS_FONT_SIZE}" text-anchor="middle">${escapeSvgText(tick.text)}</text>`;
+  }
   for (const pen of geometry.pens) {
     if (pen.area !== "") {
       svg += `<path class="hk-trend-chart__area" d="${pen.area}" fill="${pen.color}" fill-opacity="${TREND_CHART_AREA_OPACITY}" stroke="none"/>`;
@@ -323,6 +608,14 @@ function trendChartSvg(geometry: TrendGeometry): string {
     if (pen.line !== "") {
       svg += `<polyline class="hk-trend-chart__line" points="${pen.line}" fill="none" stroke="${pen.color}" stroke-width="${TREND_CHART_LINE_WIDTH}" stroke-linejoin="round" stroke-linecap="round"/>`;
     }
+    for (const dot of pen.dots) {
+      svg += `<circle class="hk-trend-chart__dot" cx="${dot.x}" cy="${dot.y}" r="${TREND_CHART_DOT_RADIUS}" fill="${escapeSvgText(dot.fill)}"${dot.hint !== undefined ? ` data-hint="${escapeSvgText(dot.hint)}"` : ""}/>`;
+    }
+  }
+  for (const guide of geometry.guides) {
+    if (guide.label !== undefined) {
+      svg += `<text class="hk-trend-chart__guide-label" x="${guide.labelX}" y="${guide.labelY}" fill="${escapeSvgText(guide.color)}" font-size="${TREND_CHART_AXIS_FONT_SIZE}" text-anchor="start">${escapeSvgText(guide.label)}</text>`;
+    }
   }
   svg += "</svg>";
   return svg;
@@ -341,6 +634,23 @@ export interface RenderTrendChartOptions {
   height?: number | string;
   /** Draw the alarm threshold guides; default true. */
   showThresholds?: boolean;
+  /** Chart-level horizontal guides (the named tier lines); default none. */
+  guides?: readonly TrendGuide[];
+  /** Formats the y-axis gridline numbers (floor/mid/ceiling of the shown
+   * domain); absent → no y-axis text. */
+  yAxisFormat?: (value: number) => string;
+  /** A mid/ceiling number whose gridline sits within this many viewBox px
+   * of a guide's line is dropped; default 0 (nothing dropped). */
+  yAxisClearancePx?: number;
+  /** Baseline tick count, clamped to the shown sample count; needs
+   * `xTickFormat`. Default: no x ticks. */
+  xTickCount?: number;
+  /** Formats each tick's epoch ms; needs `xTickCount`. */
+  xTickFormat?: (timeMs: number) => string;
+  /** The stepped y extent rule; absent → the raw extent flat-pad. */
+  yDomain?: TrendYDomain;
+  /** The SVG fit; default "none" (the mirror's stretch-to-box). */
+  preserveAspectRatio?: "none" | "xMidYMid meet";
 }
 
 /**
@@ -367,6 +677,14 @@ export function renderTrendChartSvg(
     options.width ?? TREND_CHART_WIDTH,
     height,
     options.showThresholds ?? true,
+    {
+      guides: options.guides,
+      yDomain: options.yDomain,
+      yAxisFormat: options.yAxisFormat,
+      yAxisClearancePx: options.yAxisClearancePx,
+      xTickCount: options.xTickCount,
+      xTickFormat: options.xTickFormat,
+    },
   );
-  return trendChartSvg(geometry);
+  return trendChartSvg(geometry, options.preserveAspectRatio ?? "none");
 }