@celestia-island/hikari 0.55.40 → 0.55.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.40",
+  "version": "0.55.42",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkContextMenuProvider.tsx

@@ -0,0 +1,137 @@
+/**
+ * HkContextMenuProvider.tsx — mount-once host of the app's context menu.
+ *
+ * Renders nothing of its own except the default slot plus ONE menu: a
+ * `HkMenu` (popup variant) whose anchor is a zero-size synthetic rect at
+ * the pointer that opened it. Everything a menu needs — desktop popout
+ * vs mobile bottom sheet, viewport flipping, popup z-stack, outside
+ * click, Escape, keyboard navigation, cascading submenus — is the shared
+ * select-panel machinery, so a context menu is styled and behaves like
+ * every other menu in the family.
+ *
+ * The placement picks the quadrant the pointer sits in (menus grow away
+ * from the nearest edge); HkSelectPanel still auto-flips when its side
+ * cannot host the panel, so the quadrant choice is a preference, not a
+ * constraint.
+ *
+ * Mount once near the app root:
+ *
+ *   <HContextMenuProvider> <App/> </HContextMenuProvider>
+ *
+ * Consumers open menus through `useContextMenu()` /
+ * `useContextMenuTrigger()` (composables/useContextMenu).
+ */
+
+import { computed, defineComponent, provide, ref, shallowRef } from "vue";
+
+import HkMenu from "./HkMenu";
+import {
+  CONTEXT_MENU_KEY,
+  type ContextMenuApi,
+  type ContextMenuRequest,
+} from "../composables/useContextMenu";
+
+/** Pick the HkMenu placement that grows away from the pointer's nearest
+ * edges: `bottom-*` when there is more room below, `*-start` when there
+ * is more room to the right. */
+function quadrantPlacement(x: number, y: number): "bottom-start" | "bottom-end" | "top-start" | "top-end" {
+  const below = y <= (typeof window !== "undefined" ? window.innerHeight : 0) / 2;
+  const right = x <= (typeof window !== "undefined" ? window.innerWidth : 0) / 2;
+  if (below && right) return "bottom-start";
+  if (below) return "bottom-end";
+  return right ? "top-start" : "top-end";
+}
+
+/** Zero-size client rect at the open point — the same synthetic-anchor
+ * trick HkMenu's cascades use, so the shared panel positions a menu at a
+ * POINTER exactly like it positions a submenu at a row. */
+function pointAnchor(x: number, y: number): HTMLElement {
+  return {
+    getBoundingClientRect: () =>
+      ({
+        x, y,
+        left: x, top: y, right: x, bottom: y,
+        width: 0, height: 0,
+        toJSON: () => ({}),
+      }) as DOMRect,
+    contains: () => false,
+  } as unknown as HTMLElement;
+}
+
+export default defineComponent({
+  name: "HkContextMenuProvider",
+  setup(_, { slots }) {
+    const open = ref(false);
+    const request = shallowRef<ContextMenuRequest | null>(null);
+    /** Remount identity: every open() swaps the HkMenu instance, so a
+     *  replacement menu starts from a CLEAN slate — cascade levels,
+     *  back-guard, hovered submenus — without racing a
+     *  close-then-reopen toggle through Vue's scheduler (a same-tick
+     *  double open, or the reactive-proxy identity trap, both ride
+     *  that race; R2 NEW-MAJOR-1/NEW-MINOR-1). */
+    const menuEpoch = ref(0);
+    /** The select handler just ran: HkMenu follows `select` with
+     *  `update:open(false)` (select first, then closeAll — HkMenu's
+     *  onItem). That trailing close belongs to the FINISHED menu: it
+     *  must not fire the new request's onClose nor close a menu the
+     *  onSelect handler opened in the meantime. One-shot flag. */
+    let justSelected = false;
+
+    /** Close hooks fire exactly once per open. */
+    function close(announce: boolean) {
+      if (!open.value) return;
+      open.value = false;
+      if (announce) request.value?.onClose?.();
+      request.value = null;
+    }
+
+    const api: ContextMenuApi = {
+      open(next: ContextMenuRequest) {
+        request.value = next;
+        menuEpoch.value += 1;
+        open.value = true;
+      },
+      close() {
+        close(true);
+      },
+    };
+    provide(CONTEXT_MENU_KEY, api);
+
+    const anchor = computed(() =>
+      pointAnchor(request.value?.x ?? 0, request.value?.y ?? 0),
+    );
+    const placement = computed(() =>
+      quadrantPlacement(request.value?.x ?? 0, request.value?.y ?? 0),
+    );
+
+    return () => (
+      <>
+        {slots.default?.()}
+        <HkMenu
+          key={menuEpoch.value}
+          variant="popup"
+          items={request.value?.items ?? []}
+          open={open.value}
+          onUpdate:open={(v: boolean) => {
+            if (!v && justSelected) {
+              justSelected = false;
+              return;
+            }
+            if (!v) close(true);
+          }}
+          onSelect={(key: string, item: { key: string }) => {
+            const current = request.value;
+            if (!current) return;
+            justSelected = true;
+            open.value = false;
+            request.value = null;
+            current.onSelect?.(key, item as Parameters<NonNullable<ContextMenuRequest["onSelect"]>>[1]);
+          }}
+          anchorRef={anchor.value}
+          placement={placement.value}
+          title={request.value?.title ?? ""}
+        />
+      </>
+    );
+  },
+});

package/src/components/HkModal.scss

@@ -475,8 +475,13 @@
     //   clip-path sweep (the only transition left on phones).
     //
     // Desktop keeps the full base list (height + max-height + clip-path).
+    // 0.3s = the stepflow crossfade's family standard (2026-09-21 user
+    // spec, round 7): the clip sweep, the riding body and the fade must
+    // land together. Keyboard-driven height changes never animate
+    // through this list (height/max-height are not transitioned), so
+    // only content morphs ride this duration.
     transition:
-      clip-path var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
+      clip-path var(--hk-modal-morph-duration, 0.3s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
     // !important beats the inline maxWidth (width prop); base width: 100%
     // already applies at every viewport, so only the cap is re-asserted.
     max-width: 100% !important;

package/src/components/HkModal.sheetgap.test.ts

@@ -121,3 +121,15 @@ describe("HkModal mobile sheet spacing contract", () => {
     });
   });
 });
+
+// 2026-09-21 user spec, round 7: the phone sheet's clip sweep shares the
+// stepflow crossfade's 0.3s family duration (the pair must land together).
+describe("HkModal phone morph duration contract", () => {
+  it("rides the clip sweep on --hk-modal-morph-duration (0.3s default)", () => {
+    const block = src.slice(src.indexOf("@media (max-width: 767px)"));
+    const content = block.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
+    expect(content).toMatch(
+      /clip-path var\(--hk-modal-morph-duration, 0\.3s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\)/,
+    );
+  });
+});

package/src/components/HkModal.sheetmorph.test.ts

@@ -63,6 +63,16 @@ describe("sheet family morph-performance contract", () => {
     );
   });
 
+  it("slows the phone sheet's clip sweep to the crossfade's 0.3s", () => {
+    // 2026-09-21 user spec, round 7: the clip sweep, the riding body and
+    // the fade must land together — the phone block overrides the fast
+    // desktop timing with the stepflow family standard. Desktop keeps
+    // the fast pair above.
+    expect(mobileModal).toMatch(
+      /^[ \t]*clip-path var\(--hk-modal-morph-duration, 0\.3s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
+    );
+  });
+
   it("never backdrop-filters the docked modal sheet or its scrim", () => {
     expect(mobileModal).toMatch(
       /^[ \t]*backdrop-filter:[ \t]*var\(--hk-modal-blur-mobile, none\);$/m,

package/src/components/HkModal.tsx

@@ -1,15 +1,4 @@
-import {
-  computed,
-  defineComponent,
-  nextTick,
-  onBeforeUnmount,
-  onMounted,
-  ref,
-  shallowRef,
-  Teleport,
-  watch,
-  type PropType,
-} from "vue";
+import { computed, defineComponent, nextTick, onBeforeUnmount, onMounted, ref, shallowRef, Teleport, watch, type PropType,  } from "vue";
 
 import { useI18n } from "../i18n/context";
 import "./HkModal.scss";
@@ -23,6 +12,8 @@ import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
 import { useSurfaceContentHold } from "../composables/useSurfaceContentHold";
 import { useSizeMorph } from "../composables/useSizeMorph";
+
+import { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
 import HButton from "./HkButton";
 import HFab from "./HkFab";
 import HSpinner from "./HkSpinner";
@@ -218,6 +209,22 @@ export default defineComponent({
     let previouslyFocused: HTMLElement | null = null;
     let unmounted = false;
 
+    // HkStepFlow swaps dispatch STEPFLOW_SWAP_EVENT (bubbling) from the
+    // flow root the moment the entering body owns the flow height. The
+    // morph's settle debounce is tuned for streaming bursts, but a step
+    // swap is one clean change whose sheet sweep must start on the SAME
+    // frames as the crossfade (2026-09-21 user spec, round 7) — so the
+    // event short-circuits straight into remeasure().
+    const onStepflowSwap = (): void => {
+      if (machine.phase.value === "open") morph.remeasure();
+    };
+    onMounted(() => {
+      bodyRef.value?.addEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
+    });
+    onBeforeUnmount(() => {
+      bodyRef.value?.removeEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
+    });
+
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
     const contentZ = computed(() => (handle.value?.zIndex ?? 0) + 1);
     const resolvedWidth = computed(() =>

package/src/components/HkNodeCanvas.edges.test.tsx

@@ -0,0 +1,336 @@
+import { describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkNodeCanvas from "./HkNodeCanvas";
+import type { NodeCanvasEdge } from "./nodeCanvasTypes";
+
+/** Mount a component into a detached div appended to the body. */
+function mountToDom(component: ReturnType<typeof defineComponent>): HTMLElement {
+  const el = document.createElement("div");
+  document.body.appendChild(el);
+  const app = createApp(component);
+  app.mount(el);
+  return el;
+}
+
+function pointerEvent(type: string, init: PointerEventInit = {}): PointerEvent {
+  return new PointerEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    pointerId: 1,
+    pointerType: "touch",
+    buttons: 1,
+    ...init,
+  });
+}
+
+/** Direct-child paths of the visible edge groups (the ink strokes). */
+function el2StrokeCount(el: HTMLElement): number {
+  return el.querySelectorAll(".hk-node-canvas-edge > path:not(.hk-node-canvas-edge-halo)").length;
+}
+
+const EDGES: NodeCanvasEdge[] = [
+  { id: "e1", from: { x: 0, y: 0 }, to: { x: 100, y: 100 }, type: "rpc", width: 1.4 },
+  { id: "e2", from: { x: 0, y: 50 }, to: { x: 100, y: 150 }, type: "proxy", width: 1.6 },
+];
+
+interface EdgeHostProps {
+  interactive?: boolean;
+  selectedEdgeId?: string | null;
+  hoverDimming?: boolean;
+}
+
+/** Host wiring the slice of the canvas API the events describe. */
+function makeEdgeHost(collected: {
+  hover: Array<string | null>;
+  click: string[];
+  context: string[];
+  prevented: boolean[];
+}) {
+  return defineComponent({
+    props: {
+      interactive: { type: Boolean, default: true },
+      selectedEdgeId: { type: String as () => string | null, default: null },
+      hoverDimming: { type: Boolean, default: true },
+    },
+    setup(props: EdgeHostProps) {
+      return () =>
+        h(HkNodeCanvas, {
+          edges: EDGES,
+          interactiveEdges: props.interactive ?? true,
+          selectedEdgeId: props.selectedEdgeId ?? null,
+          hoverDimming: props.hoverDimming ?? true,
+          minimap: false,
+          onEdgeHover: (edge: NodeCanvasEdge | null) => collected.hover.push(edge ? edge.id : null),
+          onEdgeClick: (edge: NodeCanvasEdge) => collected.click.push(edge.id),
+          onEdgeContextmenu: (edge: NodeCanvasEdge, event: { preventDefault(): void }) => {
+            collected.context.push(edge.id);
+            event.preventDefault();
+            collected.prevented.push(true);
+          },
+        }, { default: () => h("div", "content") });
+    },
+  });
+}
+
+/**
+ * HkNodeCanvas interactive edge layer — the hover/click/contextmenu
+ * contract topology hosts consume:
+ *
+ *  - off by default (no hit strokes, no halo paths);
+ *  - hit strokes re-enable pointer events per stroke and sit on top;
+ *  - hover highlights the edge and dims the rest (dimming optional);
+ *  - selection outlives hover; a vanished hovered edge clears the hover;
+ *  - click after a pan capture is the gesture's tail, not a pick;
+ *  - contextmenu is prevented and reported, and a touch hold
+ *    synthesizes one at the press point;
+ *  - explicit subpaths render (and hit) one stroke per subpath.
+ */
+describe("HkNodeCanvas interactive edges", () => {
+  it("renders no hit strokes or halos when not interactive", () => {
+    const Host = defineComponent({
+      setup() {
+        return () =>
+          h(HkNodeCanvas, { edges: EDGES, minimap: false }, { default: () => h("div", "x") });
+      },
+    });
+    const el = mountToDom(Host);
+    expect(el.querySelectorAll(".hk-node-canvas-edge-hit")).toHaveLength(0);
+    expect(el.querySelectorAll(".hk-node-canvas-edge-halo")).toHaveLength(0);
+    // Visible strokes still render.
+    expect(el2StrokeCount(el)).toBe(2);
+  });
+
+  it("highlights the hovered edge and dims the rest", async () => {
+    const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+    const el = mountToDom(makeEdgeHost(collected));
+    const hits = el.querySelectorAll(".hk-node-canvas-edge-hit[data-edge-id='e1']");
+    expect(hits.length).toBe(1);
+    hits[0].dispatchEvent(pointerEvent("pointerenter", { pointerType: "mouse" }));
+    await nextTick();
+    expect(collected.hover).toEqual(["e1"]);
+    const groups = el.querySelectorAll(".hk-node-canvas-edge");
+    expect(groups[0].classList.contains("is-hovered")).toBe(true);
+    expect(groups[1].classList.contains("is-dimmed")).toBe(true);
+    hits[0].dispatchEvent(pointerEvent("pointerleave", { pointerType: "mouse" }));
+    await nextTick();
+    expect(collected.hover).toEqual(["e1", null]);
+    expect(groups[1].classList.contains("is-dimmed")).toBe(false);
+  });
+
+  it("keeps a selected edge lit through hover changes", async () => {
+    const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+    const Host = defineComponent({
+      setup() {
+        return () =>
+          h(makeEdgeHost(collected), { selectedEdgeId: "e2" });
+      },
+    });
+    const el = mountToDom(Host);
+    el.querySelector(".hk-node-canvas-edge-hit[data-edge-id='e1']")
+      ?.dispatchEvent(pointerEvent("pointerenter", { pointerType: "mouse" }));
+    await nextTick();
+    const groups = el.querySelectorAll(".hk-node-canvas-edge");
+    expect(groups[1].classList.contains("is-selected")).toBe(true);
+    // The selected edge does NOT dim while another is hovered.
+    expect(groups[1].classList.contains("is-dimmed")).toBe(false);
+    expect(groups[0].classList.contains("is-hovered")).toBe(true);
+  });
+
+  it("reports edge clicks unless a pan was captured", async () => {
+    const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+    const el = mountToDom(makeEdgeHost(collected));
+    const root = el.querySelector(".hk-node-canvas") as HTMLElement;
+    const hit = el.querySelector(".hk-node-canvas-edge-hit[data-edge-id='e1']") as HTMLElement;
+
+    hit.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+    expect(collected.click).toEqual(["e1"]);
+
+    // A pan: pointerdown on the root, move past the slop (capture), up.
+    root.dispatchEvent(pointerEvent("pointerdown", { clientX: 100, clientY: 100, button: 0, pointerType: "mouse" }));
+    root.dispatchEvent(pointerEvent("pointermove", { clientX: 140, clientY: 100, pointerType: "mouse" }));
+    root.dispatchEvent(pointerEvent("pointerup", { pointerType: "mouse" }));
+    hit.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await nextTick();
+    expect(collected.click).toEqual(["e1"]); // the post-pan click was eaten
+  });
+
+  it("prevents and reports contextmenu on a hit stroke", async () => {
+    const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+    const el = mountToDom(makeEdgeHost(collected));
+    const event = new MouseEvent("contextmenu", { bubbles: true, cancelable: true });
+    el.querySelector(".hk-node-canvas-edge-hit[data-edge-id='e2']")
+      ?.dispatchEvent(event);
+    await nextTick();
+    expect(collected.context).toEqual(["e2"]);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("synthesizes contextmenu from a touch long-press", () => {
+    vi.useFakeTimers();
+    try {
+      const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+      const el = mountToDom(makeEdgeHost(collected));
+      const hit = el.querySelector(".hk-node-canvas-edge-hit[data-edge-id='e1']") as HTMLElement;
+      hit.dispatchEvent(pointerEvent("pointerdown", { clientX: 40, clientY: 40 }));
+      vi.advanceTimersByTime(500);
+      expect(collected.context).toEqual(["e1"]);
+      // Moving past the slop before the hold fires cancels it.
+      hit.dispatchEvent(pointerEvent("pointerdown", { clientX: 40, clientY: 40 }));
+      hit.dispatchEvent(pointerEvent("pointermove", { clientX: 70, clientY: 40 }));
+      vi.advanceTimersByTime(500);
+      expect(collected.context).toEqual(["e1"]); // no second open
+      hit.dispatchEvent(pointerEvent("pointerup"));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("suppresses the native contextmenu that follows a synthesized long-press", () => {
+    vi.useFakeTimers();
+    try {
+      const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+      const el = mountToDom(makeEdgeHost(collected));
+      const hit = el.querySelector(".hk-node-canvas-edge-hit[data-edge-id='e1']") as HTMLElement;
+      hit.dispatchEvent(pointerEvent("pointerdown", { clientX: 40, clientY: 40 }));
+      vi.advanceTimersByTime(500);
+      expect(collected.context).toEqual(["e1"]);
+      // The platform synthesizes a contextmenu right after the hold at
+      // the SAME spot: suppressed (prevented), not emitted again.
+      const native = new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 40, clientY: 40 });
+      hit.dispatchEvent(native);
+      expect(collected.context).toEqual(["e1"]);
+      expect(native.defaultPrevented).toBe(true);
+      // A real right-click ELSEWHERE inside the window is a new
+      // gesture — it must emit (R2 NEW-MINOR-2).
+      const elsewhere = new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 400, clientY: 300 });
+      hit.dispatchEvent(elsewhere);
+      expect(collected.context).toEqual(["e1", "e1"]);
+      // …and at the same spot once the window has expired.
+      vi.advanceTimersByTime(600);
+      const later = new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 40, clientY: 40 });
+      hit.dispatchEvent(later);
+      expect(collected.context).toEqual(["e1", "e1", "e1"]);
+      hit.dispatchEvent(pointerEvent("pointerup"));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("exports every explicit subpath of an edge (bus trunk + stubs)", () => {
+    const busEdge: NodeCanvasEdge = {
+      id: "bus",
+      from: { x: 0, y: 0 },
+      to: { x: 100, y: 0 },
+      subpaths: [
+        { d: "M 0 0 L 0 20", width: 1.4 },
+        { d: "M 0 20 L 100 20", width: 5 },
+        { d: "M 100 20 L 100 0", width: 1.4 },
+      ],
+    };
+    const exposed: { exportSVG?: () => SVGElement | undefined } = {};
+    const Host = defineComponent({
+      setup() {
+        const canvas = ref<{ exportSVG: () => SVGElement } | null>(null);
+        exposed.exportSVG = () => canvas.value?.exportSVG();
+        return () =>
+          h(HkNodeCanvas, {
+            ref: canvas,
+            edges: [busEdge],
+            minimap: false,
+          }, { default: () => h("div", "x") });
+      },
+    });
+    mountToDom(Host);
+    const svg = exposed.exportSVG?.();
+    expect(svg).toBeDefined();
+    const paths = svg!.querySelectorAll("path");
+    // R2 V4: the whole bundle exports, not just the first run.
+    expect(paths).toHaveLength(3);
+    expect(paths[1].getAttribute("stroke-width")).toBe("5");
+  });
+
+  it("cancels the hold when the pan captures the pointer (R1 MAJOR-1)", () => {
+    vi.useFakeTimers();
+    try {
+      const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+      const el = mountToDom(makeEdgeHost(collected));
+      const root = el.querySelector(".hk-node-canvas") as HTMLElement;
+      const hit = el.querySelector(".hk-node-canvas-edge-hit[data-edge-id='e1']") as HTMLElement;
+      // Touch press on the edge, then the press becomes a PAN: the root
+      // captures the pointer once the travel passes its slop — from
+      // then on the hit stroke hears nothing more. The hold must die
+      // with the capture, or a long drag would end in a menu.
+      hit.dispatchEvent(pointerEvent("pointerdown", { clientX: 100, clientY: 100 }));
+      root.dispatchEvent(pointerEvent("pointerdown", { clientX: 100, clientY: 100, button: 0 }));
+      root.dispatchEvent(pointerEvent("pointermove", { clientX: 160, clientY: 100 }));
+      vi.advanceTimersByTime(800);
+      expect(collected.context).toEqual([]);
+      root.dispatchEvent(pointerEvent("pointerup"));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("renders and hits explicit subpaths (bus trunk + stubs)", async () => {
+    const busEdge: NodeCanvasEdge = {
+      id: "bus",
+      from: { x: 0, y: 0 },
+      to: { x: 100, y: 0 },
+      subpaths: [
+        { d: "M 0 0 L 0 20", width: 1.4 },
+        { d: "M 0 20 L 100 20", width: 5 },
+        { d: "M 100 20 L 100 0", width: 1.4 },
+      ],
+    };
+    const Host = defineComponent({
+      setup() {
+        return () =>
+          h(HkNodeCanvas, {
+            edges: [busEdge],
+            interactiveEdges: true,
+            minimap: false,
+          }, { default: () => h("div", "x") });
+      },
+    });
+    const el = mountToDom(Host);
+    const group = el.querySelector(".hk-node-canvas-edge[data-edge-id='bus']") as HTMLElement;
+    // 3 halo + 3 ink strokes.
+    expect(group.querySelectorAll("path")).toHaveLength(6);
+    // ONE combined hit path per edge (all subpath runs concatenated —
+    // crossing a stub→trunk boundary inside the same edge must not
+    // chatter enter/leave), its width the fattest of the members'.
+    const hits = el.querySelectorAll(".hk-node-canvas-edge-hit[data-edge-id='bus']");
+    expect(hits).toHaveLength(1);
+    const hit = hits[0] as SVGPathElement;
+    expect((hit.getAttribute("d") ?? "").split("M").length - 1).toBe(3);
+    expect(Number(hit.getAttribute("stroke-width"))).toBeGreaterThan(5);
+  });
+
+  it("clears the hover when the hovered edge disappears", async () => {
+    const collected = { hover: [] as Array<string | null>, click: [] as string[], context: [] as string[], prevented: [] as boolean[] };
+    const edges = ref<NodeCanvasEdge[]>([...EDGES]);
+    const Host = defineComponent({
+      setup() {
+        return () =>
+          h(HkNodeCanvas, {
+            edges: edges.value,
+            interactiveEdges: true,
+            minimap: false,
+            onEdgeHover: (edge: NodeCanvasEdge | null) => collected.hover.push(edge ? edge.id : null),
+          }, { default: () => h("div", "x") });
+      },
+    });
+    const el = mountToDom(Host);
+    el.querySelector(".hk-node-canvas-edge-hit[data-edge-id='e1']")
+      ?.dispatchEvent(pointerEvent("pointerenter", { pointerType: "mouse" }));
+    await nextTick();
+    expect(collected.hover).toEqual(["e1"]);
+    edges.value = EDGES.filter((e) => e.id !== "e1");
+    await nextTick();
+    // The vanish reported a leave so no stale hover class persists.
+    expect(collected.hover).toEqual(["e1", null]);
+    expect(el.querySelector(".hk-node-canvas-edge.is-hovered")).toBeNull();
+  });
+});

package/src/components/HkNodeCanvas.scss

@@ -64,3 +64,44 @@
   top: var(--space-12);
   inset-inline-start: var(--space-12);
 }
+
+/* ── Interactive edges ───────────────────────────────────────────────
+   The halo paths are always in the DOM when `interactiveEdges` is on but
+   invisible until their edge is hovered or selected, so highlighting
+   costs no re-layout — only a visibility/opacity flip. Dimming fades the
+   strokes that are neither hovered nor selected while one is hovered,
+   which is what makes "which line am I on" readable on a busy canvas. */
+.hk-node-canvas-edge-halo {
+  visibility: hidden;
+}
+
+.hk-node-canvas-edge.is-hovered .hk-node-canvas-edge-halo,
+.hk-node-canvas-edge.is-selected .hk-node-canvas-edge-halo {
+  visibility: visible;
+  opacity: 0.28;
+}
+
+.hk-node-canvas-edge.is-selected .hk-node-canvas-edge-halo {
+  opacity: 0.4;
+}
+
+.hk-node-canvas-edge.is-dimmed > path:not(.hk-node-canvas-edge-halo) {
+  opacity: 0.25;
+}
+
+.hk-node-canvas-edge.is-dimmed text {
+  opacity: 0.4;
+}
+
+
+/* The invisible fat strokes that carry the pointer events. Transparent
+   (not none) so hit-testing still sees them; the cursor tells the user
+   the line is a target. A press-and-hold must not also summon the
+   platform's text-selection UI (iOS magnifier / callout). Hosts binding
+   their own long-press targets outside the canvas need the same
+   properties on those elements — see bindContextMenu's doc note. */
+.hk-node-canvas-edge-hit {
+  cursor: pointer;
+  user-select: none;
+  -webkit-touch-callout: none;
+}