@celestia-island/hikari 0.55.270 → 0.55.272

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.270",
+  "version": "0.55.272",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",
@@ -71,7 +71,6 @@
     "@xterm/addon-image": "^0.10.0-beta.301",
     "@xterm/xterm": "^6.1.0-beta.304",
     "dompurify": "^*",
-    "echarts": "^*",
     "highlight.js": "^*",
     "lucide-vue-next": "^*",
     "marked": "^*"

package/src/components/HkDonutChart.test.tsx

@@ -45,6 +45,22 @@ describe("HkDonutChart", () => {
     ]);
   });
 
+  it("gives the ring svg intrinsic dimensions from the size prop", () => {
+    // Without width/height attributes the svg has no intrinsic size and
+    // collapses to 0x0 inside the block-level ring-wrap (wowsp measured a
+    // 0x0 getBoundingClientRect on the consuming page before this fix).
+    const byDefault = mount(<HkDonutChart entries={ENTRIES} />);
+    const defaultSvg = byDefault.querySelector("svg.hk-donut__ring");
+    expect(defaultSvg?.getAttribute("width")).toBe("150");
+    expect(defaultSvg?.getAttribute("height")).toBe("150");
+
+    const custom = mount(<HkDonutChart entries={ENTRIES} size={96} />);
+    const customSvg = custom.querySelector("svg.hk-donut__ring");
+    expect(customSvg?.getAttribute("width")).toBe("96");
+    expect(customSvg?.getAttribute("height")).toBe("96");
+    expect(customSvg?.getAttribute("viewBox")).toBe("0 0 96 96");
+  });
+
   it("defaults hints to label · value · percent", () => {
     const el = mount(<HkDonutChart entries={ENTRIES} />);
     const first = el.querySelector(".hk-donut__slice");

package/src/components/HkDonutChart.tsx

@@ -46,7 +46,7 @@ export default defineComponent({
   props: {
     /** The slices' source rows; pass count-desc for the wowsp look. */
     entries: { type: Array as PropType<HkDonutEntry[]>, required: true },
-    /** Square ring size (px). */
+    /** Square ring size (px) — the SVG's intrinsic width/height and viewBox. */
     size: { type: Number, default: 150 },
     /** Legend rows per column. */
     legendRows: { type: Number, default: LEGEND_ROWS_PER_COLUMN },
@@ -102,7 +102,12 @@ export default defineComponent({
       return (
         <div class="hk-donut" role="img" aria-label={aria.value}>
           <div class="hk-donut__ring-wrap">
-            <svg class="hk-donut__ring" viewBox={`0 0 ${props.size} ${props.size}`}>
+            <svg
+              class="hk-donut__ring"
+              width={props.size}
+              height={props.size}
+              viewBox={`0 0 ${props.size} ${props.size}`}
+            >
               {slices.value.map((s) => (
                 <path
                   key={s.key}

package/src/components/HkModal.scss

@@ -619,7 +619,14 @@
     // padding both consume the vars, so one override moves both.
     --hk-scroll-pad-top: 1rem;
     --hk-scroll-pad-right: 1rem;
-    --hk-scroll-pad-bottom: 1rem;
+    // The sheet docks flush on the bottom edge (bottom: 0 above), which on
+    // a gesture-nav phone is INSIDE the system bar's band — the body's
+    // last row would sit under the home pill. The footer already clears
+    // safe area below; a footer-less body gets the same guarantee through
+    // its own bottom gutter (2026-11-02 wowsp phone report). Hosts that
+    // paint edge-to-edge content still opt out per surface with
+    // --hk-scroll-pad-bottom, the same escape hatch the footer contract has.
+    --hk-scroll-pad-bottom: calc(1rem + env(safe-area-inset-bottom, 0px));
     --hk-scroll-pad-left: 1rem;
   }
 

package/src/components/HkScrollContainer.fade.contract.test.ts

@@ -1,15 +1,30 @@
 /**
- * Source contract for the scroll-container edge fades (the 2026-10
- * revision): each edge owns a CSS var and the viewport mask INTERSECTS a
- * vertical and a horizontal gradient, so a two-axis container fades on all
- * four sides and the corners fall off naturally.
+ * Source contract for the scroll-container edge fades (the 2026-11-02
+ * revision of the 2026-10 composition): each edge owns a CSS var, the
+ * viewport mask is built from the gradient LAYERS listed in
+ * --hk-scroll-fade-layers, and the axis rules swap that list —
  *
- * The regression this pins (user report: "the light effect is clipped at
- * the two sides"): the old sheet wrote ONE `mask-image` per axis, so the
- * last matching rule won, the other axis never faded, and its band ended in
- * a hard cut. Vertical fades were missing entirely. Hence:
- *   - exactly ONE mask declaration pair lives in the sheet (the composed
+ *   - two-axis containers list the vertical AND horizontal gradients and
+ *     intersect them, so the fade reaches zero on all four sides and the
+ *     corners fall off naturally;
+ *   - single-axis containers list ONE gradient on their scroll axis:
+ *     a composed mask needs `mask-composite`, and engines without the
+ *     standard property (Android WebViews below Chromium 120 — Tauri on
+ *     Android rides the system WebView) fall back to the default ADD
+ *     composition, whose union of two opaque layers is fully opaque —
+ *     the fade vanished and the band ended in a hard cut at the screen
+ *     edge (wowsp phone report 2026-11-02: the settings tab strip sliced
+ *     its last pill mid-glyph). One layer needs no composite anywhere.
+ *
+ * The earlier regression this still pins (user report: "the light effect
+ * is clipped at the two sides"): the pre-2026-10 sheet wrote ONE
+ * `mask-image` per axis in competing cascade, so the last rule won, the
+ * other axis never faded. The axis rules now swap a VAR, never the
+ * property — the property pair is declared exactly once. Hence:
+ *   - exactly ONE mask declaration pair lives in the sheet (the base
  *     block on the viewport) — a new per-axis `mask-image` rule is drift;
+ *   - the single-axis axis rules set --hk-scroll-fade-layers to a single
+ *     gradient and touch no mask property;
  *   - all four edge vars are declared (top/right/bottom/left, 0px base);
  *   - start/end/both rules exist for BOTH axes;
  *   - RTL swaps the horizontal vars instead of rewriting the mask.
@@ -23,22 +38,52 @@ const here = dirname(fileURLToPath(import.meta.url));
 const sheet = readFileSync(join(here, "HkScrollContainer.scss"), "utf-8");
 
 describe("scroll fade composition contract", () => {
-  it("declares one composed mask on the viewport (no per-axis overrides)", () => {
+  it("declares one mask property pair on the viewport (no per-axis overrides)", () => {
     // Feature 2026-10-31: a `mask-image` is authored as
     // `@include mask-image(...)` (styles/polyfill.scss), so the include —
     // not the raw declaration — is what a sheet may carry. The mixin
     // itself owns the -webkit-/standard pair.
     const declarations = sheet.match(/^\s*@include mask-image\(/gm) ?? [];
-    // Exactly THREE pairs live in the sheet, all accounted for: the
-    // composed two-axis block on the viewport, and one feather pair per
-    // selection-hint painter (the 2026-10-30 inline falloff). Anything
-    // else is per-axis mask drift.
+    // Exactly THREE pairs live in the sheet, all accounted for: the base
+    // block on the viewport (fed by --hk-scroll-fade-layers), and one
+    // feather pair per selection-hint painter (the 2026-10-30 inline
+    // falloff). Anything else is per-axis mask drift — the axis rules
+    // must swap the VAR, never re-declare the property (the 2026-10
+    // competing-cascade regression).
     expect(declarations.length, "one include per mask pair, no per-axis drift").toBe(3);
     expect(sheet).not.toMatch(/^\s*-webkit-mask-image:/m);
+    // The composed default (two layers, four edges) still goes through
+    // mask-composite — that pair belongs to the base rule only.
     expect(sheet).toContain("mask-composite: intersect");
     expect(sheet).toContain("-webkit-mask-composite: source-in");
   });
 
+  it("declares the layer list and swaps it per axis to a single gradient", () => {
+    // The base rule lists BOTH gradients (the four-edge composition) in
+    // one var the mask property consumes.
+    expect(sheet).toMatch(/--hk-scroll-fade-layers:[\s\S]*linear-gradient\([\s\S]*to bottom[\s\S]*linear-gradient\([\s\S]*to right/);
+    // Each single-axis rule lists ONE gradient on its scroll axis — the
+    // no-composite form old WebViews render instead of an opaque union.
+    expect(
+      sheet.match(/\[data-axis="horizontal"\][^\n]*\n\s*--hk-scroll-fade-layers: linear-gradient\(\s*to right/),
+      "horizontal containers fade with one to-right gradient",
+    ).toBeTruthy();
+    expect(
+      sheet.match(/\[data-axis="vertical"\][^\n]*\n\s*--hk-scroll-fade-layers: linear-gradient\(\s*to bottom/),
+      "vertical containers fade with one to-bottom gradient",
+    ).toBeTruthy();
+    // The axis rules swap the var only — no composite, no mask property.
+    const axisBlocks = sheet.match(
+      /\.hk-scroll-container\[data-axis="(?:horizontal|vertical)"\]:is\([^)]*\)[^{]*\{[\s\S]*?\n\}/g,
+    ) ?? [];
+    expect(axisBlocks.length, "both axis swap rules exist").toBe(2);
+    for (const block of axisBlocks) {
+      expect(block).toContain("--hk-scroll-fade-layers: linear-gradient(");
+      expect(block).not.toContain("mask-composite");
+      expect(block).not.toContain("mask-image");
+    }
+  });
+
   it("declares the four edge vars with zero defaults", () => {
     for (const edge of ["top", "right", "bottom", "left"]) {
       expect(sheet).toContain(`--hk-scroll-fade-${edge}: 0px;`);

package/src/components/HkScrollContainer.scss

@@ -42,23 +42,37 @@
 }
 
 /* ── Optional edge fades (fade=true / dock fades) ─────────────────
-   FOUR-EDGE composition (2026-10 revision): each edge owns a CSS var, and
-   the viewport's mask INTERSECTS a vertical and a horizontal gradient, so
-   the fade reaches zero on every side that hides content and the corners
-   fall off naturally in all four directions. The previous per-axis rules
-   overwrote one `mask-image` property, so a two-axis container only faded
-   one axis AND the band ended in a hard cut at the other axis's edges
-   (user report: the light effect is clipped at the two sides). Vertical
-   fades were missing entirely. Dock fades ride the same vars, which also
-   removes their old mask-override conflict. */
+   Each edge owns a CSS var; the viewport's mask is built from gradient
+   LAYERS listed in --hk-scroll-fade-layers. Two-axis containers list the
+   vertical and horizontal gradients and INTERSECT them (mask-composite),
+   so the fade reaches zero on every side that hides content and the
+   corners fall off naturally in all four directions (2026-10 revision;
+   the earlier per-axis rules overwrote one `mask-image` property, so a
+   two-axis container only faded one axis AND the band ended in a hard
+   cut at the other axis's edges — user report: the light effect is
+   clipped at the two sides. Vertical fades were missing entirely).
+
+   SINGLE-axis containers list ONE gradient on their scroll axis instead
+   (2026-11-02 revision): a composed mask needs `mask-composite`, which
+   older engines without the standard property (Android WebViews below
+   Chromium 120 — Tauri on Android rides the system WebView) fall back to
+   the default ADD composition on, and the union of two opaque layers is
+   fully opaque — the fade vanished and the overflow band ended in a hard
+   cut at the screen edge (wowsp phone report 2026-11-02: the settings
+   tab strip sliced its last pill mid-glyph). A single layer needs no
+   composite on any engine, and a single-axis container's cross-axis
+   gradient is the identity anyway (its edge vars stay 0px), so the
+   rendering is unchanged on engines that composed correctly. The
+   composite pair stays on the base rule: with one layer it is a no-op
+   (there is no layer below to composite against), so the axis rules only
+   swap the layer list. Dock fades ride the same vars — they feed the
+   vertical gradient, so they land on vertical and two-axis containers. */
 .hk-scroll-container:is([data-fade="true"], [data-dock-fade]) > .hk-scroll-container-viewport {
   --hk-scroll-fade-top: 0px;
   --hk-scroll-fade-right: 0px;
   --hk-scroll-fade-bottom: 0px;
   --hk-scroll-fade-left: 0px;
-  -webkit-mask-composite: source-in;
-  -webkit-mask-repeat: no-repeat;
-  @include mask-image(
+  --hk-scroll-fade-layers:
     linear-gradient(
       to bottom,
       transparent 0,
@@ -72,12 +86,38 @@
       #000 var(--hk-scroll-fade-left),
       #000 calc(100% - var(--hk-scroll-fade-right)),
       transparent 100%
-    )
-  );
+    );
+  -webkit-mask-composite: source-in;
+  -webkit-mask-repeat: no-repeat;
+  @include mask-image(var(--hk-scroll-fade-layers));
   mask-composite: intersect;
   mask-repeat: no-repeat;
 }
 
+/* Horizontal axis (HTabs pill strips, horizontal rails): one gradient,
+   no composite required — readable on any engine that knows
+   -webkit-mask-image. */
+.hk-scroll-container[data-axis="horizontal"]:is([data-fade="true"], [data-dock-fade]) > .hk-scroll-container-viewport {
+  --hk-scroll-fade-layers: linear-gradient(
+    to right,
+    transparent 0,
+    #000 var(--hk-scroll-fade-left),
+    #000 calc(100% - var(--hk-scroll-fade-right)),
+    transparent 100%
+  );
+}
+
+/* Vertical axis (the default): same treatment on the scroll axis. */
+.hk-scroll-container[data-axis="vertical"]:is([data-fade="true"], [data-dock-fade]) > .hk-scroll-container-viewport {
+  --hk-scroll-fade-layers: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--hk-scroll-fade-top),
+    #000 calc(100% - var(--hk-scroll-fade-bottom)),
+    transparent 100%
+  );
+}
+
 .hk-scroll-container[data-fade="true"] {
   --hk-scroll-fade-size: var(--space-24);
 }

package/src/components/HkSettingsDialog.phonesheet.contract.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Source contract for the phone settings sheet (2026-11-02): the docked
+ * sheet's settings shell must FILL the modal body instead of keeping the
+ * desktop band, and the mobile body gutter must clear the gesture-nav
+ * safe area.
+ *
+ * The regression this pins (wowsp phone report 2026-11-02, screenshots of
+ * the attributions section): the host rule kept `.hk-settings` at
+ * height: var(--hk-settings-height, calc(70vh - 6.5rem)) on phones too,
+ * so on a sheet tall enough to dwarf that band the shell ended
+ * mid-screen — the pane's viewport sliced the last card mid-row and
+ * everything below it was unreachable dead sheet background. And a
+ * footer-less sheet body docked flush on the bottom edge put its last
+ * row inside the Android gesture-nav band, which only the mobile FOOTER
+ * padding handled before.
+ *
+ * The reads normalize CRLF first: sibling source contracts match
+ * raw bytes and choke on autocrlf checkouts (they fail identically on
+ * pristine master there, and pass in CI's LF checkout) — this file must
+ * stay green on BOTH.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (p: string) => readFileSync(join(here, p), "utf-8").replace(/\r\n/g, "\n");
+
+describe("phone settings sheet contract", () => {
+  it("fills the shell with the modal body under the family breakpoint", () => {
+    const sheet = read("HkSettingsDialog.scss");
+    // The desktop band stays as the var-driven base…
+    expect(sheet).toContain(
+      ".hk-settings-host .hk-settings {",
+    );
+    expect(sheet).toContain("height: var(--hk-settings-height, calc(70vh - 6.5rem));");
+    // …and the phone branch overrides it to a full fill. The override must
+    // live INSIDE the host rule's media query — a later standalone rule
+    // would also work, but the nested form keeps the band and the fill on
+    // one cascade line (the same-specificity later-block win).
+    expect(sheet).toMatch(
+      /\.hk-settings-host \.hk-settings \{[\s\S]*?@media \(max-width: 767px\) \{\s*height: 100%;\s*\}/,
+    );
+  });
+
+  it("adds the gesture-nav safe area to the mobile body bottom gutter", () => {
+    const sheet = read("HkModal.scss");
+    // The mobile block retunes the four gutter vars; only the bottom one
+    // spends the safe area (the sheet docks flush on that edge).
+    expect(sheet).toContain("--hk-scroll-pad-top: 1rem;");
+    expect(sheet).toContain("--hk-scroll-pad-right: 1rem;");
+    expect(sheet).toContain("--hk-scroll-pad-left: 1rem;");
+    expect(sheet).toContain(
+      "--hk-scroll-pad-bottom: calc(1rem + env(safe-area-inset-bottom, 0px));",
+    );
+    // The desktop gutter defaults stay untouched.
+    expect(sheet).toContain(
+      "--hk-scroll-pad-bottom: var(--hk-pad, var(--hk-modal-padding-body, 1.5rem));",
+    );
+  });
+});

package/src/components/HkSettingsDialog.scss

@@ -167,6 +167,20 @@
 
 .hk-settings-host .hk-settings {
   height: var(--hk-settings-height, calc(70vh - 6.5rem));
+
+  /* Phone sheet: the docked sheet's body is much taller than the
+     desktop's fixed 70vh band, and a fixed height here cannot stretch —
+     the shell ended mid-sheet, the pane's viewport sliced the last card
+     mid-row, and the whole lower sheet stayed a dead background band
+     (wowsp phone report 2026-11-02). On phones the shell fills the body
+     region instead (100% of the body inner's content box, which is the
+     scroller minus its paddings), so the pane is the only scroller all
+     the way down to the sheet's tail. The --hk-settings-height contract
+     stays desktop-only: the host's height knob still sizes the desktop
+     modal, and a page-embedded shell (no host class) is untouched. */
+  @media (max-width: 767px) {
+    height: 100%;
+  }
 }
 
 /* Cancel the modal body's fixed right padding so the pane's overlay

package/src/components/HkSidebarRail.scss

@@ -86,18 +86,23 @@
    * half must be able to paint. Content clipping lives in
    * .hk-sidebar-rail-clip (inside the panel). */
   overflow: visible;
+  /* The sidebar z band (900 — above content, below floating panels),
+   * carried PERMANENTLY, not only while a peek is open (2026-11-02 user
+   * screenshot, wowsp): the straddling toggle hangs over the content
+   * column in every state, and its own z-index cannot save it — any
+   * stacking context the PANEL carries in a host (wowsp's glass
+   * backdrop-filter, a transform/opacity dress) demotes the toggle's
+   * local z into that panel, and the overhanging half then loses to
+   * plain positioned content painted later in tree order. The HOST is
+   * the elevation boundary: with the band here the whole rail subtree
+   * paints atomically above the content column no matter what contexts
+   * exist inside it, so a peek overlay, the pinned expand and the idle
+   * toggle all share one rule. */
+  z-index: var(--hk-z-sidebar, 900);
   /* The layout animation the PIN window deliberately keeps. */
   transition: width var(--duration-normal, 0.3s) ease;
 }
 
-/* A peek is an OVERLAY: the host rises to the sidebar z band (900 — above
- * content, below floating panels) so the full-width panel paints over the
- * content it temporarily covers. (The host no longer needs to toggle
- * `overflow` here: it never clips.) */
-.hk-sidebar-rail-host[data-peeking] {
-  z-index: var(--hk-z-sidebar, 900);
-}
-
 .hk-sidebar-rail-panel {
   position: absolute;
   /* Logical: the panel docks the INLINE-START edge in either direction —
@@ -191,7 +196,11 @@
 .hk-sidebar-rail-flight {
   position: absolute;
   inset: 0;
-  z-index: 2;
+  /* Local bump (--hk-z-above band): the layer only has to outrank the
+   * z-auto dissolve items it substitutes for — during a flip those items
+   * hold opacity contexts, so everything inside them (scrollbar chrome
+   * included) is trapped below this layer. */
+  z-index: var(--hk-z-above, 1);
   display: block;
   pointer-events: none;
 }
@@ -284,7 +293,14 @@
   inset-inline-end: calc(var(--hk-sidebar-rail-toggle-size, 24px) / -2 - var(--hk-sidebar-rail-border-width, 1px) / 2);
   inset-block-start: 50%;
   translate: 0 -50%;
-  z-index: 2;
+  /* The fab band — a floating circular affordance above the panel's local
+   * chrome. The ranking threat inside the panel is the overlay-scrollbar
+   * TRACK (absolute, z-index: 10 — a stacking context that also contains
+   * the thumb's 2 and the markers' 1, attached beside the sidebar body):
+   * the old raw z-index: 2 ranked BELOW that track, so a scroll or a
+   * marker flash could paint its band over the circle's inner half. The
+   * fab band clears both the track and everything inside it. */
+  z-index: var(--hk-z-fab, 40);
   opacity: 0;
   pointer-events: none;
   transition: opacity var(--duration-fast, 0.15s) ease;

package/src/components/HkSidebarRail.styles.test.ts

@@ -34,7 +34,14 @@ import {
  * 3. The toggle's center rides the border LINE: negative half-size inset
  *    (plus half the border), vertical centering, size token on the host.
  * 4. The host stays the LAYOUT box (position relative, width transition)
- *    and [data-peeking] only raises it to the sidebar z band now.
+ *    and ALWAYS carries the sidebar z band — not only under [data-peeking]
+ *    (2026-11-02 user screenshot, wowsp): the straddling toggle hangs over
+ *    the content column in every state, and a host whose panel carries its
+ *    own stacking context (wowsp's glass backdrop-filter) demotes the
+ *    toggle's local z below plain positioned content, so the band must
+ *    live on the host, the elevation boundary.
+ * 4b. No raw z-index numbers: the toggle rides the fab band, the flight
+ *    layer the local-bump band — both through the scale tokens.
  * 5. Pinning: [data-pinning] kills the panel's and any nested sidebar's
  *    width transitions (the expand must not replay the slide) while the
  *    HOST width transition stays — and the pinned panel keeps the peek
@@ -93,12 +100,19 @@ describe("HkSidebarRail geometry contract", () => {
     expect(host, "the host width transition IS the intended motion").toContain("transition: width");
   });
 
-  it("a peek only raises the host to the sidebar z band now (no clip flip)", () => {
-    const peeking = ruleBody(css, ".hk-sidebar-rail-host[data-peeking]");
-    expect(peeking, "the peeking rule exists").not.toBeNull();
-    expect(peeking).toContain("z-index: var(--hk-z-sidebar, 900)");
-    // The host no longer toggles overflow here — it never clips.
-    expect(peeking).not.toContain("overflow");
+  it("the host carries the sidebar z band ALWAYS (the stacking-trap contract)", () => {
+    // The band lives on the host rule itself, not under [data-peeking]:
+    // the toggle's overhanging half must paint above the content column in
+    // every state, and a host whose panel carries its own stacking context
+    // (wowsp's glass backdrop-filter) demotes the toggle's local z below
+    // plain positioned content painted later in tree order. There is no
+    // bare peeking z rule left to tie the elevation to the peek state.
+    const host = ruleBody(css, ".hk-sidebar-rail-host {") ?? ruleBody(css, ".hk-sidebar-rail-host");
+    expect(host, "the host rule exists").not.toBeNull();
+    expect(host).toContain("z-index: var(--hk-z-sidebar, 900)");
+    expect(css).not.toContain(".hk-sidebar-rail-host[data-peeking] {");
+    // The peek shadow survives on the panel-scoped rules.
+    expect(css).toContain(".hk-sidebar-rail-host[data-peeking] .hk-sidebar-rail-panel");
   });
 
   it("the panel overlays from the inline-start edge, unclipped, and animates its width", () => {
@@ -186,8 +200,12 @@ describe("HkSidebarRail geometry contract", () => {
     // Vertical centering on the edge.
     expect(toggle).toContain("inset-block-start: 50%");
     expect(toggle).toContain("translate: 0 -50%");
-    // Above the panel + content.
-    expect(toggle).toContain("z-index: 2");
+    // Above the panel's local chrome — through the FAB band token, never a
+    // raw number: the overlay-scrollbar thumb rides a raw 2 through
+    // uncontexted ancestors right up to this panel, so the toggle must
+    // strictly outrank it (a tie would be DOM-order roulette).
+    expect(toggle).toContain("z-index: var(--hk-z-fab, 40)");
+    expect(toggle).not.toMatch(/z-index:\s*\d/);
   });
 
   it("the peek casts its shadow toward the content side, mirrored in RTL", () => {
@@ -256,7 +274,9 @@ describe("HkSidebarRail geometry contract", () => {
     expect(layer, "the flight layer rule exists").not.toBeNull();
     expect(layer).toContain("position: absolute");
     expect(layer).toContain("inset: 0");
-    expect(layer).toContain("z-index: 2");
+    // The local-bump band token, never a raw number (see 4b).
+    expect(layer).toContain("z-index: var(--hk-z-above, 1)");
+    expect(layer).not.toMatch(/z-index:\s*\d/);
     expect(layer).toContain("pointer-events: none");
 
     const clone = ruleBody(css, ".hk-sidebar-rail-flight-clone");

package/src/components/HkTrendChart.test.tsx

@@ -0,0 +1,163 @@
+// 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).
+//
+// AI-generated (glm-5.3-flash via DeepSeek Harness), 2026-11-03 — SySL-1.0 §2.3.
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createApp, h, nextTick, ref } from "vue";
+import { afterEach, describe, expect, it } from "vitest";
+
+import HkTrendChart from "./HkTrendChart";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(props: Record<string, unknown>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => h(HkTrendChart, props) });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+const CPU = { label: "cpu", data: [{ time: 0, value: 1 }, { time: 5000, value: 4 }] };
+
+describe("HkTrendChart", () => {
+  it("renders the mirror's DOM contract on its own contents host", () => {
+    const el = mount({ pens: [CPU], now: 5000, timeWindowMs: 5000 });
+    // The root div: class hook + the old echarts wrapper's inline box.
+    const root = el.querySelector("div.hk-trend-chart") as HTMLElement;
+    expect(root).not.toBeNull();
+    // Vue serializes the inline style normalized; the box itself is the
+    // old wrapper's "width:100%;height:240px".
+    expect(root.style.width).toBe("100%");
+    expect(root.style.height).toBe("240px");
+    // The SVG mounts on its own display:contents host, exactly as the Rust
+    // mirror documents.
+    const host = root.firstElementChild as HTMLElement;
+    expect(host.style.display).toBe("contents");
+    const svg = host.querySelector("svg.hk-trend-chart__svg")!;
+    expect(svg).not.toBeNull();
+    expect(svg.getAttribute("viewBox")).toBe("0 0 640 240");
+    expect(svg.getAttribute("preserveAspectRatio")).toBe("none");
+    // One area + one line per pen, drawn with the token ladder.
+    expect(el.querySelectorAll("path.hk-trend-chart__area")).toHaveLength(1);
+    expect(el.querySelectorAll("polyline.hk-trend-chart__line")).toHaveLength(1);
+    const line = el.querySelector("polyline.hk-trend-chart__line")!;
+    expect(line.getAttribute("points")).toBe("50,200 620,30");
+    expect(line.getAttribute("stroke")).toBe("rgb(var(--color-primary))");
+    expect(line.getAttribute("stroke-width")).toBe("2");
+    const area = el.querySelector("path.hk-trend-chart__area")!;
+    expect(area.getAttribute("d")).toBe("M 50 200 L 620 30 L 620 200 L 50 200 Z");
+    expect(area.getAttribute("fill-opacity")).toBe("0.12");
+    // No chart library anywhere: no canvas, no echarts chrome.
+    expect(el.querySelectorAll("canvas")).toHaveLength(0);
+  });
+
+  it("freezes the window at the newest sample when no now prop is given", () => {
+    // now defaults to the newest sample (5000), so the visible geometry is
+    // identical to the pinned now: 5000 render above — no empty window.
+    const el = mount({ pens: [CPU], timeWindowMs: 5000 });
+    expect(el.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,200 620,30",
+    );
+  });
+
+  it("renders threshold guides into the markup, and only then", () => {
+    const el = mount({
+      pens: [{ label: "cpu", data: [{ time: 0, value: 1 }, { time: 1000, value: 9 }], thresholds: { hh: 8 } }],
+      now: 1000,
+      timeWindowMs: 1000,
+    });
+    const guide = el.querySelector("line.hk-trend-chart__threshold")!;
+    expect(guide).not.toBeNull();
+    expect(guide.getAttribute("x1")).toBe("50");
+    expect(guide.getAttribute("x2")).toBe("620");
+    expect(guide.getAttribute("stroke")).toBe("#FF1744");
+    expect(guide.getAttribute("stroke-dasharray")).toBe("6 4");
+    expect(guide.getAttribute("stroke-width")).toBe("1");
+
+    const bare = mount({ pens: [CPU], now: 5000, timeWindowMs: 5000 });
+    expect(bare.querySelectorAll("line.hk-trend-chart__threshold")).toHaveLength(0);
+    // showThresholds: false wins over present limits.
+    const hidden = mount({
+      pens: [{ label: "cpu", data: [{ time: 0, value: 1 }], thresholds: { hh: 8 } }],
+      now: 0,
+      showThresholds: false,
+    });
+    expect(hidden.querySelectorAll("line.hk-trend-chart__threshold")).toHaveLength(0);
+  });
+
+  it("lifts a px height into the viewBox and keeps non-px lengths out", () => {
+    const px = mount({ pens: [CPU], height: "120px" });
+    expect((px.querySelector("div.hk-trend-chart") as HTMLElement).style.height).toBe("120px");
+    expect(px.querySelector("svg.hk-trend-chart__svg")!.getAttribute("viewBox")).toBe("0 0 640 120");
+
+    const rem = mount({ pens: [CPU], height: "18rem" });
+    expect((rem.querySelector("div.hk-trend-chart") as HTMLElement).style.height).toBe("18rem");
+    expect(rem.querySelector("svg.hk-trend-chart__svg")!.getAttribute("viewBox")).toBe(
+      "0 0 640 240",
+    );
+
+    // An empty height keeps the viewBox-derived px on the root box.
+    const empty = mount({ pens: [CPU], height: "" });
+    expect((empty.querySelector("div.hk-trend-chart") as HTMLElement).style.height).toBe("240px");
+  });
+
+  it("is deterministic: same props, same markup (offline pre-render)", () => {
+    const a = mount({ pens: [CPU], now: 5000, timeWindowMs: 5000 });
+    const b = mount({ pens: [CPU], now: 5000, timeWindowMs: 5000 });
+    expect(a.querySelector("div.hk-trend-chart")!.innerHTML).toBe(
+      b.querySelector("div.hk-trend-chart")!.innerHTML,
+    );
+  });
+
+  it("re-renders streaming updates through reactive pens", async () => {
+    const pens = ref([{ label: "cpu", data: [{ time: 0, value: 1 }] }]);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({ render: () => h(HkTrendChart, { pens: pens.value, now: 1000, timeWindowMs: 1000 }) });
+    app.mount(container);
+    mounts.push({ app, container });
+    expect(container.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,115",
+    );
+    pens.value = [{ label: "cpu", data: [{ time: 0, value: 1 }, { time: 1000, value: 4 }] }];
+    await nextTick();
+    expect(container.querySelector("polyline.hk-trend-chart__line")!.getAttribute("points")).toBe(
+      "50,200 620,30",
+    );
+  });
+
+  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
+    // componentSelfSufficiency reads sources.
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const name of ["HkTrendChart.tsx", "trendGeometry.ts"]) {
+      const source = readFileSync(resolve(here, name), "utf8").replace(/\r\n/g, "\n");
+      expect(
+        /(?:from\s*|import\s*\(\s*)["']echarts/.test(source),
+        `${name}: chart library import`,
+      ).toBe(false);
+      // No side-effect import (i.e. no stylesheet — the mirror's styles()
+      // is empty by design).
+      expect(source.includes('import "'), `${name}: side-effect import`).toBe(false);
+    }
+    const pkg = JSON.parse(
+      readFileSync(resolve(here, "../../package.json"), "utf8"),
+    ) as { dependencies?: Record<string, string> };
+    expect(Object.keys(pkg.dependencies ?? {})).not.toContain("echarts");
+  });
+});