@celestia-island/hikari 0.55.218 → 0.55.220

package/package.json

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

package/src/components/HkTreemap.scss

@@ -124,6 +124,17 @@
   font-weight: 600;
 }
 
+/* An UNKNOWN / unattributed component is not a named category; the slant
+ * keeps it visibly distinct from every localized source label. */
+.hk-treemap__label--unknown {
+  font-style: italic;
+  opacity: 0.9;
+  /* Synthetic oblique ink leans past the last advance; the same 0.2em
+   * cushion as the family's reviewed italic-truncation rules keeps the
+   * trailing stroke inside the ellipsis box. */
+  padding-inline-end: 0.2em;
+}
+
 .hk-treemap__meta {
   opacity: 0.85;
   font-variant-numeric: tabular-nums;

package/src/components/HkTreemap.test.tsx

@@ -229,18 +229,13 @@ describe("HkTreemap pure layout input", () => {
     ).toEqual({ nodes: [], total: 0 });
   });
 
-  it("chooses readable label colours across pale, mid-tone and dark backgrounds", () => {
-    expect(contrastTextColor("#edc948")).toBe("#0b1220");
-    expect(contrastTextColor("#4e79a7")).toBe("#fff");
-    expect(contrastTextColor("#76b7b2")).toBe("#0b1220");
-    expect(contrastTextColor("rgb(242, 142, 43)")).toBe("#0b1220");
-    expect(contrastTextColor("#abc")).toBe("#0b1220");
-    expect(contrastTextColor("hsl(0, 0%, 100%)")).toBe("#0b1220");
-    expect(contrastTextColor("not-a-color")).toBe("#fff");
-    // Every default palette member must clear WCAG AA with its chosen text.
-    for (const color of HK_TREEMAP_DEFAULT_COLORS) {
-      expect(["#fff", "#0b1220"]).toContain(contrastTextColor(color));
-    }
+  it("cell labels follow the theme icon/text token, not a per-block flip", () => {
+    // User direction 2026-10-28: cells read like icon glyphs — white on the
+    // dark theme via rgb(var(--color-text)), the same vocabulary as
+    // HkIconButton; the token flips the ink in the light theme.
+    expect(contrastTextColor("#edc948")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("#4e79a7")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("not-a-color")).toBe("rgb(var(--color-text, 30 30 30))");
   });
 
   it("builds an accessible leaf-path summary from the same layout", () => {
@@ -316,6 +311,41 @@ describe("HkTreemap component", () => {
     );
   });
 
+  it("marks an explicitly unknown label with the italic label class", async () => {
+    const mounted = mountTreemap({
+      nodes: [{ id: "unknown", label: "Unknown", value: 5, labelItalic: true }],
+    });
+    await setSize(mounted, 400, 240);
+    const label = mounted.container.querySelector(".hk-treemap__cell .hk-treemap__label--unknown");
+    expect(label).not.toBeNull();
+    expect(label!.textContent).toBe("Unknown");
+    expect(label!.closest("[data-hk-tooltip-text]")?.getAttribute("data-hk-tooltip-text"))
+      .toContain("Unknown");
+    // The default-on legend must not restore an upright reading.
+    expect(mounted.container.querySelector(".hk-treemap__legend-label.hk-treemap__label--unknown"))
+      .not.toBeNull();
+  });
+
+  it("inherits labelItalic from an unknown group to its descendants", async () => {
+    const nodes: HkTreemapNode[] = [{
+      id: "unknown-group",
+      label: "Unknown group",
+      value: 0,
+      labelItalic: true,
+      children: [{ id: "child", label: "Child", value: 5 }],
+    }];
+    const layout = buildHkTreemapLayout(nodes);
+    expect(layout.nodes[0]!.labelItalic).toBe(true);
+    expect(layout.nodes[0]!.children![0]!.labelItalic).toBe(true);
+    const mounted = mountTreemap({ nodes });
+    await setSize(mounted, 400, 240);
+    const labels = [...mounted.container.querySelectorAll(".hk-treemap__label")];
+    expect(labels.length).toBeGreaterThanOrEqual(2);
+    for (const label of labels) {
+      expect(label.classList.contains("hk-treemap__label--unknown")).toBe(true);
+    }
+  });
+
   it("lays out in LOCAL px under a root zoom — never zoom× oversized (R2 S1)", async () => {
     const mounted = mountTreemap({ nodes: [{ id: "solo", label: "Solo", value: 5 }] });
     // 2× root: gBCR reports 800×480 drawn; the layout must still tile the
@@ -444,4 +474,12 @@ describe("HkTreemap chrome contract (SCSS pins)", () => {
     expect(css).toMatch(/--color-background/);
     expect(css).toMatch(/--color-muted/);
   });
+
+  it("italic unknown labels carry the reviewed horizontal overhang cushion", () => {
+    const block = css.match(/\.hk-treemap__label--unknown\s*\{([\s\S]*?)\}/)?.[1] ?? "";
+    expect(block).toContain("font-style: italic");
+    // The italic scan cannot resolve a modifier class on top of the base
+    // truncation box; pin the cushion at the source level instead.
+    expect(block).toMatch(/padding-inline-end:\s*0\.2em/);
+  });
 });

package/src/components/HkTreemap.tsx

@@ -17,6 +17,10 @@ import "./HkTreemap.scss";
 export interface HkTreemapNode {
   id: string;
   label: string;
+  /** Render the label in italics — used for an explicitly UNKNOWN /
+   *  unattributed composition bucket, which must not read as a normal
+   *  named category. Inherited by descendants. */
+  labelItalic?: boolean;
   value: number;
   /** Optional opaque sRGB colour: #rgb/#rrggbb/#rrggbbaa, rgb()/rgba() or
    *  hsl()/hsla(). Cells are DOM-painted, so any CSS colour would work at
@@ -33,6 +37,7 @@ export type HkTreemapValueFormatter = (value: number) => string;
 export interface HkTreemapLayoutNode {
   id: string;
   label: string;
+  labelItalic?: boolean;
   value: number;
   color: string;
   percent: number;
@@ -139,21 +144,18 @@ function resolveOpaqueColor(raw: string, fallback: string): string {
   return `rgb(${Math.round(channels[0])} ${Math.round(channels[1])} ${Math.round(channels[2])})`;
 }
 
-/** Pick the higher-contrast label colour for an opaque CSS background. */
-export function contrastTextColor(background: string): string {
-  const channels = parseCssColor(background);
-  if (!channels || channels[3] < 0.999) return "#fff";
-  // sRGB relative luminance, with the standard gamma expansion. The two
-  // candidate text colours (#fff / #0b1220) cross at luminance ~= 0.193.
-  const linear = (channel: number) => {
-    const value = channel / 255;
-    return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
-  };
-  const luminance =
-    0.2126 * linear(channels[0]) +
-    0.7152 * linear(channels[1]) +
-    0.0722 * linear(channels[2]);
-  return luminance > 0.193 ? "#0b1220" : "#fff";
+/**
+ * Cell label colour — user direction 2026-10-28: the text inside the colour
+ * blocks should read like the family's icon glyphs (WHITE on the dark
+ * theme), not a per-block black/white flip that made mid-tone cells carry
+ * dark text. So the foreground simply follows the theme's icon/text token
+ * (`--hi-icon-color` resolves to `rgb(var(--color-text))`), the same
+ * vocabulary HkIconButton uses; the light theme keeps dark ink via the same
+ * token. The background argument is kept for signature compatibility and
+ * intentionally unused.
+ */
+export function contrastTextColor(_background: string): string {
+  return "rgb(var(--color-text, 30 30 30))";
 }
 
 export const HK_TREEMAP_DEFAULT_COLORS = [
@@ -174,6 +176,7 @@ const defaultValueFormatter: HkTreemapValueFormatter = (value) => String(value);
 interface NumericLayoutNode {
   id: string;
   label: string;
+  labelItalic?: boolean;
   value: number;
   color: string;
   children?: NumericLayoutNode[];
@@ -191,13 +194,15 @@ function isVisibleValue(value: number): boolean {
 function normalizeNode(
   node: HkTreemapNode,
   inheritedColor: string,
+  inheritedItalic = false,
 ): NumericLayoutNode | null {
   const color = node.color
     ? resolveOpaqueColor(node.color, inheritedColor)
     : inheritedColor;
+  const labelItalic = node.labelItalic ?? inheritedItalic;
   if (node.children && node.children.length > 0) {
     const children = node.children
-      .map((child) => normalizeNode(child, color))
+      .map((child) => normalizeNode(child, color, labelItalic))
       .filter((child): child is NumericLayoutNode => child !== null);
     if (children.length === 0) return null;
 
@@ -205,11 +210,24 @@ function normalizeNode(
     // Finite inputs can still overflow when summed. Such a group cannot be
     // represented truthfully, so omit it rather than emitting Infinity/NaN.
     if (!isVisibleValue(value)) return null;
-    return { id: node.id, label: node.label, value, color, children };
+    return {
+      id: node.id,
+      label: node.label,
+      ...(labelItalic ? { labelItalic: true } : {}),
+      value,
+      color,
+      children,
+    };
   }
 
   if (!isVisibleValue(node.value)) return null;
-  return { id: node.id, label: node.label, value: node.value, color };
+  return {
+    id: node.id,
+    label: node.label,
+    ...(labelItalic ? { labelItalic: true } : {}),
+    value: node.value,
+    color,
+  };
 }
 
 function visitLeaves(nodes: NumericLayoutNode[], visit: (leaf: NumericLayoutNode) => void): void {
@@ -523,13 +541,24 @@ export default defineComponent({
             >
               {head ? (
                 <span class="hk-treemap__group-head">
-                  <span class="hk-treemap__label hk-treemap__label--group">{label}</span>
+                  <span
+                    class={{
+                      "hk-treemap__label": true,
+                      "hk-treemap__label--group": true,
+                      "hk-treemap__label--unknown": node.labelItalic,
+                    }}
+                  >{label}</span>
                   {meta && <span class="hk-treemap__meta">{meta}</span>}
                 </span>
               ) : (
                 label && (
                   <span class="hk-treemap__leaf-body">
-                    <span class="hk-treemap__label">{label}</span>
+                    <span
+                      class={{
+                        "hk-treemap__label": true,
+                        "hk-treemap__label--unknown": node.labelItalic,
+                      }}
+                    >{label}</span>
                     {meta && <span class="hk-treemap__meta">{meta}</span>}
                   </span>
                 )
@@ -558,7 +587,12 @@ export default defineComponent({
                     style={{ backgroundColor: node.color }}
                     aria-hidden="true"
                   />
-                  <span class="hk-treemap__legend-label">{node.label}</span>
+                  <span
+                    class={{
+                      "hk-treemap__legend-label": true,
+                      "hk-treemap__label--unknown": node.labelItalic,
+                    }}
+                  >{node.label}</span>
                   <span class="hk-treemap__legend-value">{valueText}</span>
                   <span class="hk-treemap__legend-percent">{percentText}</span>
                 </li>

package/src/components/HkTreemapStage.scss

@@ -1,7 +1,7 @@
-/* HkTreemapStage — the interactive treemap surface: a header with the
- * back button + drill path, the pan/zoom cell canvas (the cells reuse
- * HkTreemap's chrome classes verbatim — theme mortar, ellipsis labels),
- * and the collapsible HkMinimap pinned bottom-right. */
+/* HkTreemapStage — the interactive treemap surface: at root, no redundant
+ * header; once drilled, a breadcrumb plus the pan/zoom cell canvas (cells
+ * reuse HkTreemap's chrome — theme mortar, ellipsis labels), a bottom-right
+ * return button, and the collapsible HkMinimap. */
 
 .hk-treemap-stage {
   position: relative;
@@ -23,12 +23,6 @@
   border-bottom: 1px solid var(--border-faint);
 }
 
-/* Keeps the path centred when the back button is absent (root level). */
-.hk-treemap-stage__head-pad {
-  width: 24px;
-  flex: 0 0 auto;
-}
-
 .hk-treemap-stage__path {
   display: flex;
   align-items: center;
@@ -97,6 +91,89 @@
   inset: 0;
 }
 
+/* ── nested preview inside a big group ───────────────────────────────
+ * The group's own button remains the only interactive target; the child
+ * rectangles/labels are a non-interactive "what is inside" preview. */
+.hk-treemap-stage__nested-cell {
+  pointer-events: none;
+  overflow: hidden;
+  font-size: var(--text-2xs, 0.6875rem);
+}
+
+.hk-treemap-stage__nested-head {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  height: 22px;
+  padding: 0 0.25rem;
+  background: rgb(0 0 0 / 18%);
+  font-weight: 600;
+}
+
+.hk-treemap-stage__nested-leaf {
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+  gap: 1px;
+  min-height: 0;
+  height: 100%;
+  padding: 0.125rem 0.25rem;
+}
+
+.hk-treemap-stage__nested-label {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  /* The text-clip contract requires ≥1.3 for descenders in clipped rows. */
+  line-height: 1.3;
+}
+
+.hk-treemap-stage__nested-meta {
+  flex: 0 0 auto;
+  min-width: 0;
+  /* In the horizontal group-head row the meta MUST yield to the label so
+   * its own ellipsis pair can engage; the leaf body is a column and keeps
+   * its intrinsic height. */
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  opacity: 0.85;
+  font-variant-numeric: tabular-nums;
+}
+
+.hk-treemap-stage__nested-head .hk-treemap-stage__nested-meta {
+  flex: 0 1 auto;
+}
+
+.hk-treemap-stage__empty {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 1rem;
+  color: rgb(var(--color-muted, 108 108 108));
+  font-size: var(--text-sm, 0.8125rem);
+  pointer-events: none;
+}
+
+/* A drilled level's return control lives in the same bottom-right corner
+ * cluster as the minimap (user: the header-only back was not discoverable). */
+.hk-treemap-stage__back-float {
+  position: absolute;
+  bottom: var(--space-12, 0.75rem);
+  z-index: 51;
+  width: 32px;
+  height: 32px;
+  color: rgb(var(--color-text));
+  background: rgb(var(--color-surface) / 0.82);
+  border: 1px solid var(--border-faint);
+  border-radius: var(--radius-sm);
+  backdrop-filter: blur(var(--blur-md));
+  box-shadow: var(--shadow-dropdown);
+}
+
 /* Cells reuse .hk-treemap__cell chrome from HkTreemap.scss; the stage
  * adds the drill affordance on group cells. */
 .hk-treemap-stage__cell--drillable {

package/src/components/HkTreemapStage.test.tsx

@@ -123,7 +123,22 @@ describe("HkTreemapStage — the drill path", () => {
     const placements = [...mounted.container.querySelectorAll("[data-hk-tooltip-placement]")]
       .map((node) => node.getAttribute("data-hk-tooltip-placement"));
     expect(new Set(placements)).toEqual(new Set(["bottom"]));
-    expect(mounted.container.textContent).toContain("Usage"); // the root crumb
+    // No redundant root-level title/header; the canvas aria-label still
+    // names the surface for assistive tech.
+    expect(mounted.container.querySelector(".hk-treemap-stage__head")).toBeNull();
+    expect(mounted.container.querySelector('[aria-label="Back"]')).toBeNull();
+    // Big groups preview their children immediately (no click required).
+    const nested = [...mounted.container.querySelectorAll(".hk-treemap-stage__nested-cell")];
+    expect(nested.length).toBeGreaterThanOrEqual(2);
+    const nestedLabels = [...mounted.container.querySelectorAll(".hk-treemap-stage__nested-label")]
+      .map((node) => node.textContent);
+    expect(nestedLabels).toContain("Alpha");
+    expect(nestedLabels).toContain("Beta");
+    // Previews live INSIDE the drillable cell: parent hover/focus chrome
+    // and the click surface stay above them without a second z-layer.
+    for (const preview of nested) {
+      expect(preview.closest(".hk-treemap-stage__cell--drillable")).not.toBeNull();
+    }
   });
 
   it("keeps the tooltip-owned cell frames inside a small canvas at 2×/3× DPI", async () => {
@@ -216,7 +231,69 @@ describe("HkTreemapStage — the drill path", () => {
     expect(container.querySelector('[aria-label="Back"]')).toBeNull();
   });
 
-  it("changing the data resets the drill stack and the camera", async () => {
+  it("a same-shape live refresh preserves the drill path and camera", async () => {
+    const mounted = mountStage({ nodes: NODES });
+    await setSize(mounted);
+    const group = [...mounted.container.querySelectorAll(".hk-treemap-stage__cell--drillable")]
+      .find((c) => (c.getAttribute("aria-label") ?? "").startsWith("Group:")) as HTMLElement;
+    group.click();
+    await nextTick();
+    expect(mounted.container.querySelector('[aria-label="Back"]')).toBeTruthy();
+    const back = mounted.container.querySelector<HTMLElement>('[aria-label="Back"]')!;
+    expect(back.classList.contains("hk-treemap-stage__back-float")).toBe(true);
+
+    // A camera change made at this level must survive the refresh too.
+    const canvas = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__canvas")!;
+    canvas.dispatchEvent(new WheelEvent("wheel", {
+      deltaY: -100, bubbles: true, cancelable: true,
+    }));
+    await nextTick();
+    const surface = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__surface")!;
+    const camera = surface.style.transform;
+    expect(camera).toContain("scale(1.1)");
+
+    // Live polling hands the stage a NEW array with the same ids (updated
+    // weights). The user's drill must survive; only the values move.
+    mounted.update({
+      nodes: [
+        {
+          id: "group",
+          label: "Group",
+          value: 0,
+          children: [
+            { id: "a", label: "Alpha updated", value: 5 },
+            { id: "b", label: "Beta", value: 7 },
+          ],
+        },
+        { id: "other", label: "Other", value: 4 },
+      ],
+    });
+    await nextTick();
+    expect(mounted.container.querySelector('[aria-label="Back"]')).toBeTruthy();
+    expect(mounted.container.textContent).toContain("Alpha updated");
+    expect(mounted.container.textContent).toContain("Beta");
+    expect(mounted.container.querySelector(".hk-treemap-stage__head")).toBeTruthy();
+    expect(mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__surface")!.style.transform)
+      .toBe(camera);
+  });
+
+  it("keeps a drilled level with a localized empty message when its children vanish", async () => {
+    const mounted = mountStage({ nodes: NODES, emptyText: "Nothing inside" });
+    await setSize(mounted);
+    const group = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__cell--drillable")!;
+    group.click();
+    await nextTick();
+
+    // Same group id, refreshed into a leaf: no auto-return, no blank canvas.
+    mounted.update({ nodes: [{ id: "group", label: "Group", value: 5 }] });
+    await nextTick();
+    expect(mounted.container.querySelector('[aria-label="Back"]')).toBeTruthy();
+    expect(mounted.container.querySelector(".hk-treemap-stage__head")).toBeTruthy();
+    expect(mounted.container.querySelector(".hk-treemap-stage__empty")?.textContent)
+      .toBe("Nothing inside");
+  });
+
+  it("removing the drilled group falls back to root and clears the back control", async () => {
     const mounted = mountStage({ nodes: NODES });
     await setSize(mounted);
     const group = [...mounted.container.querySelectorAll(".hk-treemap-stage__cell--drillable")]
@@ -228,8 +305,116 @@ describe("HkTreemapStage — the drill path", () => {
     mounted.update({ nodes: [{ id: "fresh", label: "Fresh", value: 3 }] });
     await nextTick();
     expect(mounted.container.querySelector('[aria-label="Back"]')).toBeNull();
+    expect(mounted.container.querySelector(".hk-treemap-stage__head")).toBeNull();
     expect(mounted.container.textContent).toContain("Fresh");
   });
+
+  it("reveals the nested preview only when zoom makes the group large enough", async () => {
+    const nestedNodes: HkTreemapNode[] = [
+      {
+        id: "outer",
+        label: "Outer",
+        value: 0,
+        children: [{
+          id: "inner",
+          label: "Inner",
+          value: 0,
+          children: [
+            { id: "inner-a", label: "Inner A", value: 1 },
+            { id: "inner-b", label: "Inner B", value: 1 },
+          ],
+        }],
+      },
+      { id: "other", label: "Other", value: 1 },
+    ];
+    const mounted = mountStage({ nodes: nestedNodes, zoomPercent: 100 });
+    await setSize(mounted, 100, 240);
+    // The group cell is 100px wide at 100% — below the 120×90 preview
+    // gate, even though it is tall.
+    expect(mounted.container.querySelectorAll(".hk-treemap-stage__nested-cell")).toHaveLength(0);
+
+    mounted.update({ zoomPercent: 150 });
+    await nextTick();
+    const previews = [...mounted.container.querySelectorAll<HTMLElement>(".hk-treemap-stage__nested-cell")];
+    expect(previews.length).toBeGreaterThan(0);
+    // Recursion reaches the grandchild level (outer → inner → leaves) and
+    // the nested group's own label passes the zoomed label ladder.
+    expect(previews.some((cell) => cell.dataset.depth === "1")).toBe(true);
+    expect(previews.every((cell) => cell.getAttribute("aria-hidden") === "true")).toBe(true);
+    // Flat VNodes all live under the top-level cell: the grandchild must sit
+    // below/right of its nested parent by the header/pad inset. Re-basing on
+    // the nested cell's own x/y would collapse this delta to zero.
+    const depth0 = previews.find((cell) => cell.dataset.depth === "0")!;
+    const depth1 = previews.find((cell) => cell.dataset.depth === "1")!;
+    expect(Number.parseFloat(depth1.style.top) - Number.parseFloat(depth0.style.top))
+      .toBeGreaterThanOrEqual(22);
+    expect(Number.parseFloat(depth1.style.left) - Number.parseFloat(depth0.style.left))
+      .toBeGreaterThanOrEqual(2);
+    expect(mounted.container.textContent).toContain("Inner");
+    // Previews are descendants of the group button, not siblings.
+    for (const preview of previews) {
+      expect(preview.closest(".hk-treemap-stage__cell--drillable")).not.toBeNull();
+    }
+  });
+
+  it("also gates the preview on the zoomed HEIGHT, not width alone", async () => {
+    const wideShort = mountStage({
+      nodes: [{
+        id: "wide",
+        label: "Wide",
+        value: 0,
+        children: [
+          { id: "wide-a", label: "Wide A", value: 1 },
+          { id: "wide-b", label: "Wide B", value: 1 },
+        ],
+      }],
+      zoomPercent: 100,
+    });
+    await setSize(wideShort, 200, 80);
+    // Full-canvas group: 200×80 at 100% — wide enough, too short.
+    expect(wideShort.container.querySelectorAll(".hk-treemap-stage__nested-cell")).toHaveLength(0);
+    wideShort.update({ zoomPercent: 150 });
+    await nextTick();
+    expect(wideShort.container.querySelectorAll(".hk-treemap-stage__nested-cell").length)
+      .toBeGreaterThan(0);
+  });
+
+  it("parks the floating return control beside the minimap when it expands", async () => {
+    const mounted = mountStage({ nodes: NODES });
+    await setSize(mounted);
+    const group = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__cell--drillable")!;
+    group.click();
+    await nextTick();
+    const back = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__back-float")!;
+    const endOf = () => back.style.getPropertyValue("inset-inline-end");
+    expect(endOf()).toBe("50px"); // 12px gutter + 30px collapsed map + 8px gap
+
+    (mounted.container.querySelector(".hk-minimap--collapsed") as HTMLElement).click();
+    await nextTick();
+    expect(endOf()).toBe("180px"); // expanded map is 160px wide
+  });
+
+  it("renders an unknown child label in italics", async () => {
+    const mounted = mountStage({
+      nodes: [{
+        id: "group",
+        label: "Group",
+        value: 0,
+        children: [
+          { id: "known", label: "Known", value: 3 },
+          { id: "unknown", label: "Unknown", value: 9, labelItalic: true },
+        ],
+      }],
+    });
+    await setSize(mounted);
+    // A large unknown leaf also gets a top-level italic label when drilled.
+    const group = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__cell--drillable")!;
+    group.click();
+    await nextTick();
+    const unknown = mounted.container.querySelector(".hk-treemap__label--unknown");
+    expect(unknown).not.toBeNull();
+    expect(unknown!.textContent).toBe("Unknown");
+  });
 });
 
 describe("HkTreemapStage — the camera + minimap", () => {

package/src/components/HkTreemapStage.tsx

@@ -1,11 +1,12 @@
 import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch,
-  type PropType } from "vue";
+  type PropType, type VNode } from "vue";
 import { ChevronLeft } from "lucide-vue-next";
 
 import HkIconButton from "./HkIconButton";
 import HkMinimap, { type MinimapBox } from "./HkMinimap";
 import HkTooltip from "./HkTooltip";
 import { drawnScale } from "../composables/layoutGeometry";
+import { useI18n } from "../i18n/context";
 import {
   buildHkTreemapLayout,
   contrastTextColor,
@@ -21,13 +22,13 @@ import "./HkTreemapStage.scss";
 
 const defaultValueFormatter: HkTreemapValueFormatter = (value) => String(value);
 
-/** One step of the drill path: the node plus its layout at that level. */
-interface DrillStep {
-  /** The node id at this level ("root" for the top). */
-  id: string;
-  label: string;
-  /** The layout nodes visible at this step (root's children, or the drilled
-   *  group's children). */
+/** The live resolution of the drill path against the CURRENT layout. */
+interface ResolvedDrill {
+  /** Valid ids (a refresh that removed a hop truncates here). */
+  ids: string[];
+  /** The nodes along the path, for the breadcrumb. */
+  nodes: HkTreemapLayoutNode[];
+  /** The children shown on the canvas at this level. */
   siblings: HkTreemapLayoutNode[];
 }
 
@@ -37,9 +38,13 @@ interface DrillStep {
  *
  *  - DRILL: clicking a GROUP cell zooms into it — its children re-lay out
  *    at the full canvas, so cells that were slivers reveal their labels,
- *    meta and nested structure ("部分方块在放大的时候才会显示更多的细
- *    节"). The header carries a BACK button (ChevronLeft, the family icon
- *    chrome) plus the drill path; clicking an earlier hop pops back to it.
+ *    meta and nested structure. The drill path survives live data refreshes
+ *    (ids, not snapshots); at root there is NO header/title, and a drilled
+ *    level shows the breadcrumb plus a floating return button in the
+ *    bottom-right control cluster beside the minimap.
+ *  - PREVIEW: a group large enough to subdivide paints its child cells in
+ *    place (non-interactive) — the operator sees some of the composition
+ *    before choosing to drill.
  *  - PAN/ZOOM: the camera scales/translates the cell layer; the ±/slider
  *    zoom bar (via the collapsible HkMinimap pinned bottom-right) steps
  *    50–200%, and dragging the minimap pans. Larger zoom rungs enlarge
@@ -73,6 +78,7 @@ export default defineComponent({
     select: (_id: string) => true,
   },
   setup(props, { emit }) {
+    const { t } = useI18n();
     const hostRef = ref<HTMLElement | null>(null);
     const size = ref<{ w: number; h: number } | null>(null);
     let observer: ResizeObserver | undefined;
@@ -161,13 +167,33 @@ export default defineComponent({
       panY.value = 0;
     }
 
-    // ── the drill stack ───────────────────────────────────────────────
+    // ── the drill path ────────────────────────────────────────────────
+    // Store IDS, never a children snapshot. Live parent refreshes allocate
+    // a new tree (same ids, updated tokens) on every poll; resolving the
+    // path against the current layout keeps the operator's drill/camera
+    // instead of silently snapping back to root (the reported regression).
     const layout = computed(() => buildHkTreemapLayout(props.nodes));
-    const drill = ref<DrillStep[]>([]);
-    const current = computed<DrillStep>(() => {
-      const step = drill.value[drill.value.length - 1];
-      if (step) return step;
-      return { id: "root", label: "", siblings: layout.value.nodes };
+    const drillPath = ref<string[]>([]);
+    const resolvedDrill = computed<ResolvedDrill>(() => {
+      let siblings = layout.value.nodes;
+      const nodes: HkTreemapLayoutNode[] = [];
+      let valid = 0;
+      for (const id of drillPath.value) {
+        const next = siblings.find((node) => node.id === id);
+        if (!next) break;
+        nodes.push(next);
+        siblings = next.children ?? [];
+        valid += 1;
+      }
+      return { ids: drillPath.value.slice(0, valid), nodes, siblings };
+    });
+
+    // Only an actually invalidated hop changes the path. A same-shape data
+    // refresh does not touch state at all.
+    watch(resolvedDrill, (resolved) => {
+      if (resolved.ids.length === drillPath.value.length) return;
+      drillPath.value = resolved.ids;
+      resetCamera();
     });
 
     function pushDrill(node: HkTreemapLayoutNode): void {
@@ -175,10 +201,7 @@ export default defineComponent({
         emit("select", node.id);
         return;
       }
-      drill.value = [
-        ...drill.value,
-        { id: node.id, label: node.label, siblings: node.children },
-    ];
+      drillPath.value = [...drillPath.value, node.id];
       // Drilling is itself a zoom: reset the pan so the new level starts
       // framed; the zoom rung stays (the user picked it).
       panX.value = 0;
@@ -186,22 +209,11 @@ export default defineComponent({
     }
 
     function popTo(index: number): void {
-      drill.value = drill.value.slice(0, index);
+      drillPath.value = drillPath.value.slice(0, index);
       panX.value = 0;
       panY.value = 0;
     }
 
-    // A changed LAYOUT invalidates the drill stack. Watching the layout
-    // (not the array identity) catches the in-place mutation a consumer
-    // can make (the computed recomputes off contents). Inline
-    // `:nodes="[...]"` literals still reset on every parent re-render —
-    // the layout allocates a fresh tree per recompute — so pass a stable
-    // reference from hot parents (known limitation, delta review F3).
-    watch(layout, () => {
-      drill.value = [];
-      resetCamera();
-    });
-
     // ── measurement (LOCAL px — the dpiPrefs root-zoom lesson) ────────
     function measure() {
       const el = hostRef.value;
@@ -228,14 +240,20 @@ export default defineComponent({
       resizeCleanup?.();
       resizeCleanup = undefined;
     });
-    watch([layout, current], measure);
+    watch([layout, resolvedDrill], measure);
 
     // ── cells at the current level ────────────────────────────────────
     const cells = computed<HkTreemapCell[]>(() => {
       const dims = size.value;
       if (!dims || layout.value.nodes.length === 0) return [];
-      return layoutHkTreemapCells(current.value.siblings, 0, 0, dims.w, dims.h);
+      return layoutHkTreemapCells(resolvedDrill.value.siblings, 0, 0, dims.w, dims.h);
     });
+    /** A drilled node can be refreshed into a leaf with no visible
+     *  children. Keep the level (and its return control) instead of
+     *  silently bouncing home, but explain the empty canvas. */
+    const levelEmpty = computed(() =>
+      hasData.value && resolvedDrill.value.nodes.length > 0 && cells.value.length === 0,
+    );
 
     const formatValue = (value: number) =>
       (props.valueFormatter ?? defaultValueFormatter)(value);
@@ -266,6 +284,13 @@ export default defineComponent({
       internalMinimapCollapsed.value = v;
       emit("update:minimapCollapsed", v);
     }
+    /** Park the floating return button beside the minimap, whether folded
+     *  (30px) or expanded (160px), so the control stays in the same corner
+     *  cluster instead of jumping to the top header. */
+    const backInsetEnd = computed(() => {
+      const minimapWidth = minimapIsCollapsed.value ? 30 : 160;
+      return `${12 + minimapWidth + 8}px`;
+    });
 
     // ── render ────────────────────────────────────────────────────────
     function cellText(node: HkTreemapLayoutNode): string {
@@ -278,23 +303,117 @@ export default defineComponent({
       transformOrigin: "0 0",
     }));
 
+    // ── nested preview ────────────────────────────────────────────────
+    // A big group already contains a laid-out child tree. Paint it in
+    // place (labels/meta allowed to degrade, exact like the standalone
+    // treemap) so the operator sees WHICH parts make up the block before
+    // drilling. Purely visual: pointer-events:none keeps the whole group
+    // one click target.
+    const NESTED_MIN_W = 120;
+    const NESTED_MIN_H = 90;
+    const NESTED_RECURSE_W = 90;
+    const NESTED_RECURSE_H = 70;
+    const NESTED_MAX_DEPTH = 3;
+
+    function renderNestedCell(
+      cell: HkTreemapCell,
+      key: string,
+      depth: number,
+      originX: number,
+      originY: number,
+    ): VNode[] {
+      const { node, x, y, w, h } = cell;
+      if (w < 2 || h < 2) return [];
+      const zoom = zoomPct.value / 100;
+      const zw = w * zoom;
+      const zh = h * zoom;
+      const isGroup = cell.children.length > 0;
+      const showLabel = zh >= 18 && zw >= 24;
+      const showValue = zh >= 40 && zw >= 56;
+      const meta = showValue
+        ? `${formatValue(node.value)} · ${formatHkTreemapPercent(node.percent)}`
+        : null;
+      const label = (
+        <span
+          class={{
+            "hk-treemap-stage__nested-label": true,
+            "hk-treemap__label--group": isGroup,
+            "hk-treemap__label--unknown": node.labelItalic,
+          }}
+        >{node.label}</span>
+      );
+      const out: VNode[] = [
+        <div
+          key={key}
+          class={{
+            "hk-treemap__cell": true,
+            "hk-treemap-stage__nested-cell": true,
+          }}
+          style={{
+            position: "absolute",
+            left: `${x - originX}px`,
+            top: `${y - originY}px`,
+            width: `${w}px`,
+            height: `${h}px`,
+            background: node.color,
+            "--hk-treemap-fg": contrastTextColor(node.color),
+          }}
+          data-depth={depth}
+          aria-hidden="true"
+        >
+          {isGroup ? (
+            showLabel && (
+              <span class="hk-treemap-stage__nested-head">
+                {label}
+                {meta && <span class="hk-treemap-stage__nested-meta">{meta}</span>}
+              </span>
+            )
+          ) : (
+            showLabel && (
+              <span class="hk-treemap-stage__nested-leaf">
+                {label}
+                {meta && <span class="hk-treemap-stage__nested-meta">{meta}</span>}
+              </span>
+            )
+          )}
+        </div>,
+      ];
+      if (
+        isGroup
+        && depth < NESTED_MAX_DEPTH
+        && w * zoom >= NESTED_RECURSE_W
+        && h * zoom >= NESTED_RECURSE_H
+      ) {
+        for (const child of cell.children) {
+          // The returned VNodes are FLAT siblings under the top-level group
+          // cell (not DOM children of this nested cell), so every depth keeps
+          // the entry origin. Passing this cell's x/y shifts grandchildren up
+          // and left by the accumulated padding/header inset.
+          out.push(...renderNestedCell(child, `${key}/${child.node.id}`, depth + 1, originX, originY));
+        }
+      }
+      return out;
+    }
+
+    /** Child previews rendered INSIDE the top-level group cell, so the
+     *  cell's hover/focus ring and click surface stay above them without a
+     *  second stacking layer. */
+    function renderNestedPreview(cell: HkTreemapCell): VNode[] {
+      if (cell.children.length === 0) return [];
+      // The same zoom-aware ladder as the labels: a group that becomes
+      // visually large at a higher rung reveals its inside too.
+      const zoom = zoomPct.value / 100;
+      if (cell.w * zoom < NESTED_MIN_W || cell.h * zoom < NESTED_MIN_H) return [];
+      return cell.children.flatMap((child) =>
+        renderNestedCell(child, `nested:${cell.node.id}/${child.node.id}`, 0, cell.x, cell.y),
+      );
+    }
+
     return () => (
       <div class="hk-treemap-stage">
-        {hasData.value && (
+        {hasData.value && resolvedDrill.value.nodes.length > 0 && (
           <header class="hk-treemap-stage__head">
-            {drill.value.length > 0 ? (
-              <HkIconButton
-                size={24}
-                variant="ghost"
-                aria-label="Back"
-                onClick={() => popTo(drill.value.length - 1)}
-              >
-                {{ icon: () => <ChevronLeft size={15} /> }}
-              </HkIconButton>
-            ) : (
-              <span class="hk-treemap-stage__head-pad" aria-hidden="true" />
-            )}
-            <nav class="hk-treemap-stage__path" aria-label="Drill path">
+            <nav class="hk-treemap-stage__path" aria-label={t("hikari::treemap.drillPath", "Drill path")}>
               <button
                 type="button"
                 class="hk-treemap-stage__crumb"
@@ -303,13 +422,14 @@ export default defineComponent({
               >
                 {props.ariaLabel}
               </button>
-              {drill.value.map((step, i) => (
+              {resolvedDrill.value.nodes.map((step, i) => (
                 <span key={step.id} class="hk-treemap-stage__crumb-seg">
                   <span class="hk-treemap-stage__crumb-sep" aria-hidden="true">/</span>
                   <button
                     type="button"
                     class="hk-treemap-stage__crumb"
-                    data-last={i === drill.value.length - 1 || undefined}
+                    data-last={i === resolvedDrill.value.nodes.length - 1 || undefined}
+                    aria-current={i === resolvedDrill.value.nodes.length - 1 ? "page" : undefined}
                     onClick={() => popTo(i + 1)}
                   >
                     {step.label}
@@ -377,7 +497,13 @@ export default defineComponent({
                         >
                           {isGroup ? (
                             <span class="hk-treemap__group-head">
-                              <span class="hk-treemap__label hk-treemap__label--group">
+                              <span
+                                class={{
+                                  "hk-treemap__label": true,
+                                  "hk-treemap__label--group": true,
+                                  "hk-treemap__label--unknown": node.labelItalic,
+                                }}
+                              >
                                 {node.label}
                               </span>
                               {showValue && (
@@ -389,7 +515,12 @@ export default defineComponent({
                           ) : (
                             showLabel && (
                               <span class="hk-treemap__leaf-body">
-                                <span class="hk-treemap__label">{node.label}</span>
+                                <span
+                                  class={{
+                                    "hk-treemap__label": true,
+                                    "hk-treemap__label--unknown": node.labelItalic,
+                                  }}
+                                >{node.label}</span>
                                 {showValue && (
                                   <span class="hk-treemap__meta">
                                     {formatValue(node.value)} · {formatHkTreemapPercent(node.percent)}
@@ -398,6 +529,7 @@ export default defineComponent({
                               </span>
                             )
                           )}
+                          {isGroup && renderNestedPreview(cell)}
                         </div>
                       )}
                     </HkTooltip>
@@ -409,6 +541,9 @@ export default defineComponent({
               <div class="hk-treemap__empty">{props.emptyText}</div>
             )}
           </div>
+          {levelEmpty.value && (
+            <div class="hk-treemap-stage__empty">{props.emptyText}</div>
+          )}
           {hasData.value && (
             <HkMinimap
               collapsible
@@ -429,6 +564,18 @@ export default defineComponent({
               onPanDelta={(dx: number, dy: number) => applyPanDelta(dx, dy)}
             />
           )}
+          {hasData.value && resolvedDrill.value.nodes.length > 0 && (
+            <HkIconButton
+              class="hk-treemap-stage__back-float"
+              style={{ insetInlineEnd: backInsetEnd.value }}
+              size={32}
+              variant="ghost"
+              aria-label={t("hikari::treemap.back", "Back")}
+              onClick={() => popTo(resolvedDrill.value.nodes.length - 1)}
+            >
+              {{ icon: () => <ChevronLeft size={16} /> }}
+            </HkIconButton>
+          )}
         </div>
       </div>
     );

package/src/i18n/locales/ar/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "مستوى التكبير",
     "hikari::zoomToolbar.expandMap": "إظهار الخريطة المصغّرة",
     "hikari::zoomToolbar.collapseMap": "إخفاء الخريطة المصغّرة",
+    "hikari::treemap.back": "رجوع",
+    "hikari::treemap.drillPath": "مسار التفصيل",
     "hikari::filterBar.trigger": "عوامل التصفية",
     "hikari::filterBar.apply": "تطبيق",
     "hikari::filterPanel.all": "الكل",

package/src/i18n/locales/de/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "Zoom-Stufe",
     "hikari::zoomToolbar.expandMap": "Minikarte anzeigen",
     "hikari::zoomToolbar.collapseMap": "Minikarte ausblenden",
+    "hikari::treemap.back": "Zurück",
+    "hikari::treemap.drillPath": "Drill-Pfad",
     "hikari::filterBar.trigger": "Filter",
     "hikari::filterBar.apply": "Anwenden",
     "hikari::filterPanel.all": "Alle",

package/src/i18n/locales/en/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "Zoom level",
     "hikari::zoomToolbar.expandMap": "Show minimap",
     "hikari::zoomToolbar.collapseMap": "Hide minimap",
+    "hikari::treemap.back": "Back",
+    "hikari::treemap.drillPath": "Drill path",
     "hikari::filterBar.trigger": "Filters",
     "hikari::filterBar.apply": "Apply",
     "hikari::filterPanel.all": "All",

package/src/i18n/locales/es/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "Nivel de zoom",
     "hikari::zoomToolbar.expandMap": "Mostrar minimapa",
     "hikari::zoomToolbar.collapseMap": "Ocultar minimapa",
+    "hikari::treemap.back": "Atrás",
+    "hikari::treemap.drillPath": "Ruta de exploración",
     "hikari::filterBar.trigger": "Filtros",
     "hikari::filterBar.apply": "Aplicar",
     "hikari::filterPanel.all": "Todos",

package/src/i18n/locales/fr/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "Niveau de zoom",
     "hikari::zoomToolbar.expandMap": "Afficher la mini-carte",
     "hikari::zoomToolbar.collapseMap": "Masquer la mini-carte",
+    "hikari::treemap.back": "Retour",
+    "hikari::treemap.drillPath": "Chemin d’exploration",
     "hikari::filterBar.trigger": "Filtres",
     "hikari::filterBar.apply": "Appliquer",
     "hikari::filterPanel.all": "Tous",

package/src/i18n/locales/ja/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "ズーム倍率",
     "hikari::zoomToolbar.expandMap": "ミニマップを表示",
     "hikari::zoomToolbar.collapseMap": "ミニマップを隠す",
+    "hikari::treemap.back": "戻る",
+    "hikari::treemap.drillPath": "ドリルパス",
     "hikari::filterBar.trigger": "絞り込み",
     "hikari::filterBar.apply": "適用",
     "hikari::filterPanel.all": "すべて",

package/src/i18n/locales/ko/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "확대 수준",
     "hikari::zoomToolbar.expandMap": "미니맵 표시",
     "hikari::zoomToolbar.collapseMap": "미니맵 숨기기",
+    "hikari::treemap.back": "뒤로",
+    "hikari::treemap.drillPath": "드릴 경로",
     "hikari::filterBar.trigger": "필터",
     "hikari::filterBar.apply": "적용",
     "hikari::filterPanel.all": "전체",

package/src/i18n/locales/pt/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "Nível de zoom",
     "hikari::zoomToolbar.expandMap": "Mostrar minimapa",
     "hikari::zoomToolbar.collapseMap": "Ocultar minimapa",
+    "hikari::treemap.back": "Voltar",
+    "hikari::treemap.drillPath": "Caminho de detalhamento",
     "hikari::filterBar.trigger": "Filtros",
     "hikari::filterBar.apply": "Aplicar",
     "hikari::filterPanel.all": "Todos",

package/src/i18n/locales/ru/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "Уровень масштаба",
     "hikari::zoomToolbar.expandMap": "Показать мини-карту",
     "hikari::zoomToolbar.collapseMap": "Скрыть мини-карту",
+    "hikari::treemap.back": "Назад",
+    "hikari::treemap.drillPath": "Путь детализации",
     "hikari::filterBar.trigger": "Фильтры",
     "hikari::filterBar.apply": "Применить",
     "hikari::filterPanel.all": "Все",

package/src/i18n/locales/zh-Hans/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "缩放级别",
     "hikari::zoomToolbar.expandMap": "显示小地图",
     "hikari::zoomToolbar.collapseMap": "隐藏小地图",
+    "hikari::treemap.back": "返回",
+    "hikari::treemap.drillPath": "下钻路径",
     "hikari::statusBar.region.CN": "中国大陆",
     "hikari::statusBar.region.HK": "中国香港",
     "hikari::statusBar.region.MO": "中国澳门",

package/src/i18n/locales/zh-Hant/components.json

@@ -199,6 +199,8 @@
     "hikari::zoomToolbar.zoomSlider": "縮放級別",
     "hikari::zoomToolbar.expandMap": "顯示小地圖",
     "hikari::zoomToolbar.collapseMap": "隱藏小地圖",
+    "hikari::treemap.back": "返回",
+    "hikari::treemap.drillPath": "下鑽路徑",
     "hikari::statusBar.region.CN": "中國大陸",
     "hikari::statusBar.region.HK": "中國香港",
     "hikari::statusBar.region.MO": "中國澳門",