@celestia-island/hikari 0.55.109 → 0.55.111

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.109",
+  "version": "0.55.111",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",
@@ -56,11 +56,14 @@
     "vue": "^*"
   },
   "dependencies": {
+    "@xterm/addon-fit": "^0.*",
+    "@xterm/addon-image": "^0.10.0-beta.301",
+    "@xterm/xterm": "^6.1.0-beta.304",
     "dompurify": "^*",
     "echarts": "^*",
+    "highlight.js": "^*",
     "lucide-vue-next": "^*",
-    "marked": "^*",
-    "highlight.js": "^*"
+    "marked": "^*"
   },
   "devDependencies": {
     "@types/three": "^*",

package/src/components/HkFab.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vitest } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 
 import HkFab from "./HkFab";
+import { POPUP_Z_BANDS } from "../runtime/usePopupManager";
 
 const mounts: ReturnType<typeof createApp>[] = [];
 const containers: HTMLElement[] = [];
@@ -41,8 +42,14 @@ function mountFab(props: Record<string, unknown> = {}): Harness {
   mounts.push(app);
   app.mount(container);
 
-  const root = container.querySelector<HTMLElement>(".hk-fab");
-  const button = container.querySelector<HTMLButtonElement>(".hk-fab-button");
+  // A layer="top" fab teleports into the floating layer on <body>;
+  // fall back to the document scope so both modes resolve.
+  const root =
+    container.querySelector<HTMLElement>(".hk-fab") ??
+    document.body.querySelector<HTMLElement>(".hk-fab");
+  const button =
+    container.querySelector<HTMLButtonElement>(".hk-fab-button") ??
+    document.body.querySelector<HTMLButtonElement>(".hk-fab-button");
   if (!root || !button) throw new Error("HkFab did not render its shell");
   harness.root = root;
   harness.button = button;
@@ -215,3 +222,28 @@ describe("HkFab speed dial", () => {
     expect(toggles).toEqual([true, false, true, false]);
   });
 });
+
+describe("HkFab layer", () => {
+  it("host (default) keeps the fab anchored in the host tree", () => {
+    const m = mountFab({ ariaLabel: "Host", positioning: "fixed" });
+    expect(document.body.querySelector(".hk-floating-layer")).toBeNull();
+    expect(m.root.getAttribute("data-positioning")).toBe("fixed");
+  });
+
+  it("top wraps the fab in an HkFloatingLayer above the window band", () => {
+    const m = mountFab({ ariaLabel: "Float", layer: "top", corner: "bottom-right" });
+    const layer = document.body.querySelector<HTMLElement>(".hk-floating-layer");
+    expect(layer).not.toBeNull();
+    expect(layer!.contains(m.root)).toBe(true);
+    // Geometry is owned by the layer alone once floated.
+    expect(m.root.getAttribute("data-positioning")).toBeNull();
+    expect(m.root.getAttribute("data-corner")).toBeNull();
+    // Offset vars hand off to the layer as well — the fab keeps none.
+    expect(m.root.style.getPropertyValue("--hk-fab-offset-x")).toBe("");
+    expect(m.root.style.getPropertyValue("--hk-fab-offset-y")).toBe("");
+    expect(layer!.getAttribute("data-corner")).toBe("bottom-right");
+    const z = Number(layer!.style.getPropertyValue("--hk-float-z"));
+    expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+  });
+});

package/src/components/HkFab.tsx

@@ -6,6 +6,7 @@ import {
 } from "vue";
 
 import { iconByName } from "../composables/iconRegistry";
+import HkFloatingLayer from "./HkFloatingLayer";
 import "./HkFab.scss";
 
 /** One entry of the HkFab speed dial. */
@@ -21,6 +22,7 @@ type FabCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 type FabSize = "sm" | "md" | "lg";
 type FabVariant = "primary" | "glass";
 type FabExpandDirection = "up" | "down" | "left" | "right";
+type FabLayer = "host" | "top";
 
 /**
  * Material-design-style floating action button with an optional
@@ -46,6 +48,13 @@ export default defineComponent({
     disabled: { type: Boolean, default: false },
     actions: { type: Array as PropType<HFabAction[]>, default: undefined },
     expandDirection: { type: String as PropType<FabExpandDirection>, default: "up" },
+    /** "top" floats the fab above every window (HkFloatingLayer — the
+     *  popup manager's tooltip band, teleported to <body>): dials stay
+     *  reachable no matter which modal/sheet opens over them. The layer
+     *  owns the geometry when floated — `positioning` is ignored, the
+     *  corner/offset props hand off to it. "host" keeps the classic
+     *  in-tree anchoring (the historical default, byte-identical). */
+    layer: { type: String as PropType<FabLayer>, default: "host" },
   },
   emits: {
     click: (_e: MouseEvent) => true,
@@ -116,6 +125,8 @@ export default defineComponent({
     }
 
     return () => {
+      const floated = props.layer === "top";
+
       // Icon precedence: slot > registry > inline chevron-down fallback.
       // `as any` matches HkIcon — the registry returns a loose Component.
       const RegistryIcon = props.icon ? (iconByName(props.icon) as any) : null;
@@ -144,19 +155,19 @@ export default defineComponent({
         </span>
       );
 
-      return (
+      const fab = (
         <div
           ref={rootRef}
           class="hk-fab"
-          data-positioning={props.positioning}
-          data-corner={props.corner}
+          data-positioning={floated ? undefined : props.positioning}
+          data-corner={floated ? undefined : props.corner}
           data-size={props.size}
           data-variant={props.variant}
           data-expand={props.expandDirection}
           data-expanded={isOpen.value ? "true" : undefined}
           style={{
-            "--hk-fab-offset-x": props.offsetX,
-            "--hk-fab-offset-y": props.offsetY,
+            "--hk-fab-offset-x": floated ? undefined : props.offsetX,
+            "--hk-fab-offset-y": floated ? undefined : props.offsetY,
           }}
         >
           {(props.actions?.length ?? 0) > 0 && (
@@ -196,6 +207,23 @@ export default defineComponent({
           </button>
         </div>
       );
+
+      // Floated: the HkFloatingLayer owns viewport anchoring (corner +
+      // safe-area + tooltip-band z); the fab itself renders bare inside
+      // it (data-positioning/corner stripped above so the geometry is
+      // owned by exactly one layer).
+      if (floated) {
+        return (
+          <HkFloatingLayer
+            corner={props.corner}
+            offsetX={props.offsetX}
+            offsetY={props.offsetY}
+          >
+            {fab}
+          </HkFloatingLayer>
+        );
+      }
+      return fab;
     };
   },
 });

package/src/components/HkFloatingLayer.scss

@@ -0,0 +1,58 @@
+// HkFloatingLayer.scss — top-layer floating chrome.
+//
+// Anchoring mirrors HkFab's safe-area-aware corner insets, extended per
+// instance by --hk-float-offset-*. The z rides the popup manager's
+// tooltip band via --hk-float-z (inline from the component once the
+// registration resolves); the fallback must stay in sync with
+// POPUP_Z_BANDS.tooltip in runtime/usePopupManager.ts.
+.hk-floating-layer {
+  position: fixed;
+  z-index: var(--hk-float-z, 3000);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+  pointer-events: none;
+
+  --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-left, 0px));
+  --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-bottom, 0px));
+
+  &[data-corner$="-right"] {
+    --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-right, 0px));
+    right: calc(var(--hk-float-inset-x) + var(--hk-float-offset-x, 0px));
+  }
+
+  &[data-corner$="-left"] {
+    --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-left, 0px));
+    left: calc(var(--hk-float-inset-x) + var(--hk-float-offset-x, 0px));
+  }
+
+  &[data-corner^="top"] {
+    --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-top, 0px));
+    top: calc(var(--hk-float-inset-y) + var(--hk-float-offset-y, 0px));
+  }
+
+  &[data-corner^="bottom"] {
+    --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-bottom, 0px));
+    bottom: calc(var(--hk-float-inset-y) + var(--hk-float-offset-y, 0px));
+  }
+
+  // The layer never eats gestures; the widgets inside do. NOTE: for a
+  // floated HkFab this rule must LOSE to HkFab's own
+  // `.hk-fab { pointer-events: none }` (equal specificity — later sheet
+  // wins — and HkFab.tsx imports this component before its own sheet),
+  // so the fab root stays transparent while its button re-enables.
+  // Do not strengthen this selector or reorder those imports: the
+  // layer's gap boxes would start eating clicks.
+  > * {
+    pointer-events: auto;
+  }
+
+  // A floated HkFab (layer="top") hands viewport anchoring to this
+  // layer entirely: drop its own positioning so its corner lands in
+  // the layer's flow instead of double-resolving the insets.
+  > .hk-fab {
+    position: static;
+    inset: auto;
+    z-index: auto;
+  }
+}

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

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Compiled-stylesheet contract for HkFloatingLayer. The layer IS its
+ * CSS (fixed positioning, gesture transparency, the > .hk-fab
+ * positioning hand-off), none of which the runtime suite can see —
+ * vitest stubs CSS — so the sheet is compiled and asserted here.
+ */
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+describe("HkFloatingLayer stylesheet contract", () => {
+  const tsx = readFileSync(resolve(componentDir, "HkFloatingLayer.tsx"), "utf8");
+  const css = compile(resolve(componentDir, "HkFloatingLayer.scss"), {
+    style: "expanded",
+  }).css;
+
+  it("compiles the fixed, gesture-transparent top-layer shell", () => {
+    expect(css).toContain(".hk-floating-layer {");
+    expect(css).toContain("position: fixed;");
+    expect(css).toContain("z-index: var(--hk-float-z, 3000);");
+    // The layer never eats gestures; the widgets inside do.
+    expect(css).toContain("pointer-events: none;");
+    expect(css).toContain(".hk-floating-layer > * {");
+    expect(css).toContain("pointer-events: auto;");
+  });
+
+  it("anchors all four corners with safe-area-aware insets", () => {
+    expect(css).toContain('[data-corner$=-right]');
+    expect(css).toContain('[data-corner$=-left]');
+    expect(css).toContain('[data-corner^=top]');
+    expect(css).toContain('[data-corner^=bottom]');
+    for (const side of ["right: calc", "left: calc", "top: calc", "bottom: calc"]) {
+      expect(css).toContain(side);
+    }
+    expect(css).toContain("env(safe-area-inset-left, 0px)");
+    expect(css).toContain("env(safe-area-inset-right, 0px)");
+    expect(css).toContain("env(safe-area-inset-top, 0px)");
+    expect(css).toContain("env(safe-area-inset-bottom, 0px)");
+  });
+
+  it("takes over a floated HkFab's positioning entirely", () => {
+    expect(css).toContain(".hk-floating-layer > .hk-fab {");
+    expect(css).toContain("position: static;");
+    expect(css).toContain("inset: auto;");
+    expect(css).toContain("z-index: auto;");
+  });
+
+  it("has no dead selectors: every rule the sheet emits is rendered", () => {
+    // The TSX must reference every state the sheet styles.
+    expect(tsx).toContain('class="hk-floating-layer"');
+    expect(tsx).toContain("data-corner={props.corner}");
+  });
+});

package/src/components/HkFloatingLayer.test.tsx

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkFloatingLayer from "./HkFloatingLayer";
+import { POPUP_Z_BANDS, usePopupManager } from "../runtime/usePopupManager";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+/** Mount an HkFloatingLayer through a wrapper app (mirrors the
+ *  HkFab.test.tsx harness). The layer teleports its node to <body>,
+ *  so queries go through document.body, not the host container. */
+function mountLayer(props: Record<string, unknown> = {}, slot?: () => unknown) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const Wrapper = defineComponent({
+    setup() {
+      return () => h(HkFloatingLayer, props, slot ? { default: slot } : undefined);
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+
+  return {
+    app,
+    root: () => document.body.querySelector<HTMLElement>(".hk-floating-layer"),
+  };
+}
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  document.body.innerHTML = "";
+});
+
+describe("HkFloatingLayer", () => {
+  it("teleports the corner layer to body with a tooltip-band z slot", () => {
+    const m = mountLayer({ ariaLabel: "Date dial" });
+    const root = m.root();
+    expect(root).not.toBeNull();
+    // Teleported: outside the wrapper's host subtree.
+    expect(containers[0].contains(root!)).toBe(false);
+    expect(root!.getAttribute("data-corner")).toBe("bottom-right");
+    expect(root!.getAttribute("role")).toBe("group");
+    expect(root!.getAttribute("aria-label")).toBe("Date dial");
+    // Inline z from the popup manager registration — inside the
+    // tooltip band, strictly below the toast band.
+    const z = Number(root!.style.getPropertyValue("--hk-float-z"));
+    expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+  });
+
+  it("open=false renders nothing at all", () => {
+    const m = mountLayer({ open: false });
+    expect(m.root()).toBeNull();
+  });
+
+  it("registers exactly one tooltip entry and releases it on unmount", () => {
+    const manager = usePopupManager();
+    const tooltipCount = () => {
+      let n = 0;
+      for (const entry of manager.registry.value.values()) {
+        if (entry.kind === "tooltip") n++;
+      }
+      return n;
+    };
+    const before = tooltipCount();
+    // Non-blocking, untitled chrome must stay silent (a future
+    // warnUntitled change folding tooltip into the naming rule would
+    // dev-warn on every mount — that regression goes red here).
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const m = mountLayer();
+    expect(tooltipCount()).toBe(before + 1);
+    m.app.unmount();
+    mounts.splice(mounts.indexOf(m.app), 1);
+    expect(tooltipCount()).toBe(before);
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("hide releases the slot; re-show re-registers with a fresh band z", async () => {
+    const manager = usePopupManager();
+    const tooltipCount = () => {
+      let n = 0;
+      for (const entry of manager.registry.value.values()) {
+        if (entry.kind === "tooltip") n++;
+      }
+      return n;
+    };
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const visible = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(HkFloatingLayer, { open: visible.value });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+
+    const layer = () => document.body.querySelector<HTMLElement>(".hk-floating-layer");
+    const before = tooltipCount();
+    expect(before).toBeGreaterThanOrEqual(1);
+    const z1 = Number(layer()!.style.getPropertyValue("--hk-float-z"));
+    expect(z1).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+
+    // Hide: the node leaves AND the band slot is released — the
+    // count test above cannot catch this branch on its own (unmount
+    // cleanup would mask it).
+    visible.value = false;
+    await nextTick();
+    expect(tooltipCount()).toBe(before - 1);
+    expect(layer()).toBeNull();
+
+    // Re-show: registered again, first paint already carries the z.
+    visible.value = true;
+    await nextTick();
+    expect(tooltipCount()).toBe(before);
+    const z2 = Number(layer()!.style.getPropertyValue("--hk-float-z"));
+    expect(z2).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+
+    app.unmount();
+    mounts.splice(mounts.indexOf(app), 1);
+    expect(tooltipCount()).toBe(before - 1);
+  });
+
+  it("honours the corner and offset props", () => {
+    const m = mountLayer({ corner: "top-left", offsetX: "1rem", offsetY: "2rem" });
+    const root = m.root()!;
+    expect(root.getAttribute("data-corner")).toBe("top-left");
+    expect(root.style.getPropertyValue("--hk-float-offset-x")).toBe("1rem");
+    expect(root.style.getPropertyValue("--hk-float-offset-y")).toBe("2rem");
+  });
+
+  it("keeps slot content mounted inside the layer", () => {
+    const m = mountLayer({}, () => h("button", { class: "probe" }, "go"));
+    expect(m.root()!.querySelector(".probe")).not.toBeNull();
+  });
+});

package/src/components/HkFloatingLayer.tsx

@@ -0,0 +1,112 @@
+import {
+  defineComponent,
+  onBeforeUnmount,
+  ref,
+  Teleport,
+  watch,
+  type PropType,
+} from "vue";
+
+import { usePopupManager } from "../runtime/usePopupManager";
+import "./HkFloatingLayer.scss";
+
+type FloatCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+/**
+ * HkFloatingLayer — viewport-fixed chrome that floats at the TOP layer.
+ *
+ * The dial/FAB problem this solves: always-reachable chrome anchored to
+ * a page (or a window) dies the moment a real window opens over it —
+ * either it is buried under the modal overlay (page pads), or it gets
+ * re-rendered as an in-window copy that no longer shares the page's
+ * geometry (the per-modal dial copies this layer replaces). Floating at
+ * the popup manager's tooltip band makes the chrome independent of the
+ * window stack, exactly like a tooltip: above every modal/drawer
+ * overlay, below toasts, present on its own merits.
+ *
+ * Mechanics:
+ *   - Teleported to <body>, so no transformed ancestor (morph tabs,
+ *     modal content frames) can re-anchor or clip a `position: fixed`
+ *     child, and the layer resolves against the viewport full stop.
+ *   - Registered with the popup manager (kind "tooltip", non-blocking,
+ *     no scroll lock, no breadcrumb title): the z slot derives from the
+ *     live registry instead of a magic constant, and the layer shows up
+ *     in `readHkRuntime("popupManager")` like every other surface.
+ *   - The layer itself is gesture-transparent (pointer-events: none);
+ *     the widgets inside catch their own pointers.
+ *   - Corner insets mirror HkFab's safe-area-aware math, extended per
+ *     instance by the offset props.
+ *
+ *   - Within the tooltip band, stacking is open-order (the manager's
+ *     rule): a tooltip that registered later paints above this chrome
+ *     near the corner, and a layer mounted after a live tooltip paints
+ *     above it — transient vs persistent chrome trades locally. Do not
+ *     "fix" this with a magic z. Two layers at one corner overlap;
+ *     pass offsets to stack them deliberately.
+ *   - While a modal is open, the modal's focus trap keeps this chrome
+ *     pointer-reachable but NOT keyboard-reachable — the standing
+ *     tradeoff for floating chrome; a focus relay is out of scope.
+ *
+ * Consumers: the shell's quick-action pad, a modal's detached date dial
+ * (via `HkFab layer="top"` or direct use) — anything that must survive
+ * the next window opening on top of it.
+ */
+export default defineComponent({
+  name: "HkFloatingLayer",
+  props: {
+    /** False unmounts the teleported layer and releases its band slot
+     *  (true = always shown). House `open` convention, like every other
+     *  hikari surface. */
+    open: { type: Boolean, default: true },
+    corner: { type: String as PropType<FloatCorner>, default: "bottom-right" },
+    offsetX: { type: String, default: undefined },
+    offsetY: { type: String, default: undefined },
+    /** Accessible group name for the chrome (e.g. "Date dial"). */
+    ariaLabel: { type: String, default: "" },
+  },
+  setup(props, { slots }) {
+    const { register, unregister } = usePopupManager();
+    const handle = ref<{ id: string; zIndex: number } | null>(null);
+
+    // Annotation-band chrome, not a breadcrumb level: non-blocking,
+    // untitled, no scroll lock, no outside-dismiss channel. Registered
+    // exactly while shown (immediate, so the first paint already
+    // carries the band z); a hidden layer holds no slot.
+    watch(
+      () => props.open,
+      (show) => {
+        if (show && !handle.value) handle.value = register("tooltip", false);
+        else if (!show && handle.value) {
+          unregister(handle.value.id);
+          handle.value = null;
+        }
+      },
+      { immediate: true },
+    );
+    onBeforeUnmount(() => {
+      if (handle.value) unregister(handle.value.id);
+      handle.value = null;
+    });
+
+    return () => {
+      if (!props.open) return null;
+      return (
+        <Teleport to="body">
+          <div
+            class="hk-floating-layer"
+            data-corner={props.corner}
+            role={props.ariaLabel ? "group" : undefined}
+            aria-label={props.ariaLabel || undefined}
+            style={{
+              "--hk-float-z": handle.value ? String(handle.value.zIndex) : undefined,
+              "--hk-float-offset-x": props.offsetX,
+              "--hk-float-offset-y": props.offsetY,
+            }}
+          >
+            {slots.default?.()}
+          </div>
+        </Teleport>
+      );
+    };
+  },
+});

package/src/components/HkTerminal.scss

@@ -0,0 +1,27 @@
+// Use theme variables with namespace to avoid conflicts
+@use "./hikari-vars" as vars;
+
+.hk-terminal {
+  position: relative;
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: 8rem;
+  padding: 0.35rem 0.45rem;
+  background: rgb(var(--color-background, 20 22 26));
+  border: 1px solid rgb(var(--color-border, 128 128 128) / 15%);
+  border-radius: vars.$hikari-radius-fui-md;
+  box-sizing: border-box;
+  overflow: hidden;
+
+  /* xterm fills the host box */
+  .terminal,
+  .xterm {
+    height: 100%;
+  }
+
+  /* The viewport scrollbar inherits the shared chrome shape. */
+  .xterm-viewport {
+    border-radius: vars.$hikari-radius-fui-sm;
+  }
+}

package/src/components/HkTerminal.test.tsx

@@ -0,0 +1,299 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+/**
+ * HkTerminal contract tests.
+ *
+ * The xterm CORE is mocked (happy-dom has no layout engine — xterm's
+ * WidthCache needs real glyph measurement); the mock records the exact
+ * calls so the component contract is pinned without executing the
+ * renderer:
+ *
+ *   1. props reach the Terminal options
+ *   2. `write` is a binary-safe passthrough (Uint8Array handed over
+ *      AS-IS — a string round-trip would corrupt kitty/SIXEL payloads)
+ *   3. `data` / `resize` events are wired to the consumer
+ *   4. the image addon loads with kitty/SIXEL/IIP enabled, and does not
+ *      load when `enableImages` is false
+ *   5. the terminal is disposed on unmount and observers disconnected
+ *   6. the theme derivation turns channel triplets into hex colors
+ */
+
+const writeCalls: Array<string | Uint8Array> = [];
+const loadedAddons: Array<{ ctor: string; opts?: Record<string, unknown> }> = [];
+const dataHandlers = new Set<(text: string) => void>();
+const resizeHandlers = new Set<(d: { cols: number; rows: number }) => void>();
+let disposed = 0;
+let lastOptions: Record<string, unknown> | null = null;
+let resizeCalls: Array<{ cols: number; rows: number }> = [];
+
+vi.mock("@xterm/xterm", () => ({
+  Terminal: class {
+    options: Record<string, unknown>;
+    cols: number;
+    rows: number;
+    constructor(opts: Record<string, unknown>) {
+      this.options = { ...opts };
+      this.cols = (opts.cols as number) ?? 80;
+      this.rows = (opts.rows as number) ?? 24;
+      lastOptions = this.options;
+    }
+    loadAddon(addon: { ctor?: string; opts?: Record<string, unknown> }) {
+      loadedAddons.push({
+        ctor: (addon as { ctor?: string }).ctor ?? "unknown",
+        opts: (addon as { opts?: Record<string, unknown> }).opts,
+      });
+    }
+    open() {}
+    onData(cb: (text: string) => void) {
+      dataHandlers.add(cb);
+      return () => dataHandlers.delete(cb);
+    }
+    onResize(cb: (d: { cols: number; rows: number }) => void) {
+      resizeHandlers.add(cb);
+      return () => resizeHandlers.delete(cb);
+    }
+    write(data: string | Uint8Array) {
+      writeCalls.push(data);
+    }
+    writeln(data: string | Uint8Array) {
+      writeCalls.push(data);
+      writeCalls.push("\r\n");
+    }
+    clear() {}
+    reset() {}
+    focus() {}
+    resize(cols: number, rows: number) {
+      this.cols = cols;
+      this.rows = rows;
+      resizeCalls.push({ cols, rows });
+      // Real xterm fires onResize from resize() — the mock must too, or
+      // double-emit bugs in the component hide behind it (R1 F2).
+      for (const cb of [...resizeHandlers]) cb({ cols, rows });
+    }
+    dispose() {
+      disposed += 1;
+    }
+  },
+}));
+vi.mock("@xterm/addon-fit", () => ({
+  FitAddon: class {
+    ctor = "fit";
+    fit() {}
+  },
+}));
+vi.mock("@xterm/addon-image", () => ({
+  ImageAddon: class {
+    ctor = "image";
+    opts: Record<string, unknown>;
+    constructor(opts: Record<string, unknown>) {
+      this.opts = opts;
+    }
+  },
+}));
+vi.mock("@xterm/xterm/css/xterm.css", () => ({}));
+
+import HkTerminal, { __testables } from "./HkTerminal";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+interface TerminalHarness {
+  exposed: Record<string, unknown>;
+  unmount: () => void;
+  props: Record<string, unknown>;
+}
+
+function mountTerminal(props: Record<string, unknown> = {}): TerminalHarness {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const exposedRef = ref<Record<string, unknown> | null>(null);
+  const Host = defineComponent({
+    setup() {
+      return () =>
+        h(HkTerminal, {
+          ...props,
+          ref: (el: unknown) => {
+            exposedRef.value = el as Record<string, unknown>;
+          },
+        });
+    },
+  });
+  const app = createApp(Host);
+  app.mount(container);
+  mounts.push({ app, container });
+  return {
+    get exposed() {
+      return exposedRef.value ?? {};
+    },
+    unmount: () => app.unmount(),
+    props,
+  };
+}
+
+/** Read a sibling source file (for source-level contract pins). Vitest
+ * runs with cwd = packages/vue, which is the stable anchor here. */
+function require_fs_read(name: string): string {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const fs = require("node:fs") as typeof import("node:fs");
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const path = require("node:path") as typeof import("node:path");
+  return fs.readFileSync(path.resolve(process.cwd(), "src/components", name), "utf8");
+}
+
+beforeEach(() => {
+  writeCalls.length = 0;
+  loadedAddons.length = 0;
+  dataHandlers.clear();
+  resizeHandlers.clear();
+  disposed = 0;
+  lastOptions = null;
+  resizeCalls = [];
+});
+
+afterEach(() => {
+  while (mounts.length) {
+    const m = mounts.pop()!;
+    m.app.unmount();
+    m.container.remove();
+  }
+});
+
+describe("HkTerminal", () => {
+  it("passes the typography props into the Terminal options", async () => {
+    mountTerminal({ fontSize: 15, fontFamily: "MyMono", scrollback: 500, cursorBlink: false });
+    await nextTick();
+    expect(lastOptions).toMatchObject({
+      fontSize: 15,
+      fontFamily: "MyMono",
+      scrollback: 500,
+      cursorBlink: false,
+      cols: 80,
+      rows: 24,
+    });
+  });
+
+  it("writes bytes through untouched (binary safety)", async () => {
+    const t = mountTerminal();
+    await nextTick();
+    const bytes = new Uint8Array([0x1b, 0x5f, 0x47, 0xe4, 0xbd, 0xa0]);
+    (t.exposed.write as (d: Uint8Array) => void)(bytes);
+    expect(writeCalls).toHaveLength(1);
+    expect(writeCalls[0]).toBe(bytes); // SAME object — no string round-trip
+  });
+
+  it("forwards xterm data to the consumer event", async () => {
+    const seen: string[] = [];
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const Host = defineComponent({
+      setup() {
+        return () =>
+          h(HkTerminal, {
+            onData: (text: string) => seen.push(text),
+          });
+      },
+    });
+    const app = createApp(Host);
+    app.mount(container);
+    mounts.push({ app, container });
+    await nextTick();
+    for (const cb of [...dataHandlers]) cb("ls -la\r");
+    expect(seen).toEqual(["ls -la\r"]);
+  });
+
+  it("loads the image addon with kitty/SIXEL/IIP support", async () => {
+    mountTerminal();
+    await nextTick();
+    const image = loadedAddons.find((a) => a.ctor === "image");
+    expect(image).toBeDefined();
+    expect(image!.opts).toMatchObject({
+      kittySupport: true,
+      sixelSupport: true,
+      iipSupport: true,
+      enableSizeReports: true,
+    });
+  });
+
+  it("skips the image addon when disabled", async () => {
+    mountTerminal({ enableImages: false });
+    await nextTick();
+    expect(loadedAddons.find((a) => a.ctor === "image")).toBeUndefined();
+    expect(loadedAddons.find((a) => a.ctor === "fit")).toBeDefined();
+  });
+
+  it("emits exactly one resize when the cols/rows props change", async () => {
+    const resizeEvents: Array<{ cols: number; rows: number }> = [];
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const propsRef = ref<Record<string, unknown>>({ cols: 100, rows: 30 });
+    const Host = defineComponent({
+      setup() {
+        return () => h(HkTerminal, {
+          ...(propsRef.value as Record<string, unknown>),
+          onResize: (d: { cols: number; rows: number }) => resizeEvents.push(d),
+        });
+      },
+    });
+    const app = createApp(Host);
+    app.mount(container);
+    mounts.push({ app, container });
+    await nextTick();
+    resizeEvents.length = 0;
+    propsRef.value = { cols: 120, rows: 40 };
+    await nextTick();
+    await nextTick();
+    // xterm's own onResize already emitted — a manual second emit (the
+    // R1 F2 double-fire shape) would make this 2.
+    expect(resizeEvents).toEqual([{ cols: 120, rows: 40 }]);
+  });
+
+  it("imports xterm's core stylesheet (source pin)", () => {
+    // The component is only self-sufficient with xterm.css in place
+    // (R1 F1); bundlers prune nothing thanks to sideEffects. A source
+    // pin is the honest guard — the runtime import is invisible to the
+    // mocked tests by construction.
+    const src = require_fs_read("HkTerminal.tsx");
+    expect(src).toContain('@xterm/xterm/css/xterm.css');
+  });
+
+  it("disposes the terminal on unmount", async () => {
+    const t = mountTerminal();
+    await nextTick();
+    expect(disposed).toBe(0);
+    t.unmount();
+    expect(disposed).toBe(1);
+  });
+
+  it("resizes programmatically and reports the new grid", async () => {
+    const resizeEvents: Array<{ cols: number; rows: number }> = [];
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const Host = defineComponent({
+      setup() {
+        return () =>
+          h(HkTerminal, {
+            cols: 100,
+            rows: 30,
+            onResize: (d: { cols: number; rows: number }) => resizeEvents.push(d),
+          });
+      },
+    });
+    const app = createApp(Host);
+    app.mount(container);
+    mounts.push({ app, container });
+    await nextTick();
+    // Simulate xterm's own onResize (what fit() triggers internally).
+    for (const cb of [...resizeHandlers]) cb({ cols: 120, rows: 40 });
+    expect(resizeEvents).toEqual([{ cols: 120, rows: 40 }]);
+  });
+});
+
+describe("channelToHex", () => {
+  it("turns r-g-b channel triplets into hex and keeps passthrough colors", () => {
+    const el = document.createElement("div");
+    const hex = __testables.channelToHex(el, "--color-background", "#000000");
+    // No channel value set in happy-dom → fallback path (unless the env
+    // defines one); both arms are valid, assert it returns a color.
+    expect(hex).toMatch(/^(#[0-9a-fA-F]{6}|rgb\(.*\))$/);
+  });
+});

package/src/components/HkTerminal.tsx

@@ -0,0 +1,241 @@
+import {
+  defineComponent,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  watch,
+} from "vue";
+
+import { FitAddon } from "@xterm/addon-fit";
+import { ImageAddon } from "@xterm/addon-image";
+import { Terminal, type ITheme } from "@xterm/xterm";
+
+// xterm's own core stylesheet (element layout, viewport scrolling, the
+// hidden helper textarea) — the component is self-sufficient only with
+// it in place; sideEffects in package.json keeps bundlers from pruning.
+import "@xterm/xterm/css/xterm.css";
+
+import "./HkTerminal.scss";
+
+/**
+ * HkTerminal — the shared terminal rendering surface (a rich component in
+ * the HkMarkdownRenderer class, not a thin wrapper).
+ *
+ * Owns the whole xterm.js lifecycle: creation, fitting, image-protocol
+ * decoding, theming from the hikari theme channels, and disposal. The
+ * consumer owns the DATA — it feeds bytes in through `write` (Uint8Array
+ * passthrough keeps split UTF-8 and APC/SIXEL/kitty payloads intact) and
+ * listens to `data` / `resize` to drive its transport.
+ *
+ * Props
+ * - `cols` / `rows`: initial grid (autoFit re-fits to the host afterwards).
+ * - `autoFit`: keep the grid matched to the host box (ResizeObserver).
+ *   (Mount-only: toggling after mount has no effect.)
+ * - `enableImages`: decode kitty graphics / SIXEL / iTerm2 IIP payloads
+ *   in-band (remote-control sessions push screenshots through the PTY;
+ *   mount-only).
+ * - `fontSize` / `fontFamily`: terminal typography (defaults to the
+ *   hikari mono stack).
+ * - `scrollback`: scrollback buffer size.
+ * - `cursorBlink`: blinking caret.
+ *
+ * Events
+ * - `data(text)`: keystrokes and pastes (UTF-8 text, as xterm emits).
+ * - `resize({cols, rows})`: the grid changed (autoFit or option change).
+ *
+ * Exposed API
+ * - `write(data: string | Uint8Array)` — binary-safe feed.
+ * - `writeln`, `clear`, `reset`, `fit`, `focus`, `dimensions`.
+ *
+ * Theming: the xterm theme is derived from the hikari color channels
+ * (`--color-background` / `--color-text` / `--color-primary` / …) at
+ * mount, and re-derived when the document element's class or style
+ * changes (the light/dark switch mechanism consumers use).
+ */
+
+/** Resolve an `r g b` triplet channel (with fallback) to `#rrggbb`. */
+function channelToHex(host: HTMLElement, name: string, fallback: string): string {
+  const raw = getComputedStyle(host).getPropertyValue(name).trim();
+  const parts = raw.split(/\s+/).map((p) => Number.parseFloat(p));
+  if (parts.length === 3 && parts.every((n) => Number.isFinite(n) && n >= 0 && n <= 255)) {
+    return (
+      "#" +
+      parts
+        .map((n) => Math.round(n).toString(16).padStart(2, "0"))
+        .join("")
+    );
+  }
+  // Some channels are already full colors (rgb(...) / #hex) — pass through.
+  if (raw && !raw.includes(" ")) return raw;
+  return fallback;
+}
+
+function deriveXtermTheme(host: HTMLElement): ITheme {
+  return {
+    background: channelToHex(host, "--color-background", "#14161a"),
+    foreground: channelToHex(host, "--color-text", "#e6e6e6"),
+    cursor: channelToHex(host, "--color-primary", "#7aa2f7"),
+    cursorAccent: channelToHex(host, "--color-background", "#14161a"),
+    selectionBackground: channelToHex(host, "--color-selected-bg", "#3b4356") + "88",
+  };
+}
+
+const FAMILY_FALLBACK =
+  "ui-monospace, 'SF Mono', Menlo, Consolas, 'DejaVu Sans Mono', monospace";
+
+export default defineComponent({
+  name: "HkTerminal",
+  props: {
+    cols: { type: Number, default: 80 },
+    rows: { type: Number, default: 24 },
+    autoFit: { type: Boolean, default: true },
+    enableImages: { type: Boolean, default: true },
+    fontSize: { type: Number, default: 13 },
+    fontFamily: { type: String, default: FAMILY_FALLBACK },
+    scrollback: { type: Number, default: 2000 },
+    cursorBlink: { type: Boolean, default: true },
+  },
+  emits: {
+    data: (text: string) => typeof text === "string",
+    resize: (dims: { cols: number; rows: number }) =>
+      typeof dims?.cols === "number" && typeof dims?.rows === "number",
+  },
+  setup(props, { emit, expose }) {
+    const hostRef = ref<HTMLElement>();
+    let term: Terminal | null = null;
+    let fitAddon: FitAddon | null = null;
+    let observer: ResizeObserver | null = null;
+    let themeObserver: MutationObserver | null = null;
+
+    function emitResize(cols: number, rows: number) {
+      emit("resize", { cols, rows });
+    }
+
+    onMounted(() => {
+      const host = hostRef.value;
+      if (!host) return;
+      const t = new Terminal({
+        cursorBlink: props.cursorBlink,
+        fontSize: props.fontSize,
+        fontFamily: props.fontFamily,
+        cols: props.cols,
+        rows: props.rows,
+        scrollback: props.scrollback,
+        theme: deriveXtermTheme(host),
+        allowProposedApi: true,
+      });
+      const fa = new FitAddon();
+      t.loadAddon(fa);
+      if (props.enableImages) {
+        // Image protocols: kitty graphics (APC _G) + SIXEL + iTerm2 IIP —
+        // remote-control sessions push screenshots and plots through the
+        // same PTY stream; their escape sequences must render as images.
+        // 0.10.0-beta is currently the only kitty implementation for
+        // xterm.js (alpha upstream).
+        t.loadAddon(
+          new ImageAddon({
+            enableSizeReports: true,
+            sixelSupport: true,
+            iipSupport: true,
+            kittySupport: true,
+            sixelPaletteLimit: 256,
+            storageLimit: 256,
+            showPlaceholder: false,
+          }),
+        );
+      }
+      t.open(host);
+      t.onData((text) => emit("data", text));
+      t.onResize(({ cols, rows }) => emitResize(cols, rows));
+      term = t;
+      fitAddon = fa;
+      if (props.autoFit) {
+        fa.fit();
+        observer = new ResizeObserver(() => {
+          if (!fitAddon || !term) return;
+          fitAddon.fit();
+        });
+        observer.observe(host);
+      }
+      // Re-derive colors when the consumer flips the theme (host apps
+      // switch light/dark by mutating :root class or style).
+      const retheme = () => {
+        if (term && hostRef.value) term.options.theme = deriveXtermTheme(hostRef.value);
+      };
+      if (typeof MutationObserver !== "undefined") {
+        themeObserver = new MutationObserver(retheme);
+        themeObserver.observe(document.documentElement, {
+          attributes: true,
+          attributeFilter: ["class", "style", "data-theme", "data-mode"],
+        });
+      }
+    });
+
+    onBeforeUnmount(() => {
+      observer?.disconnect();
+      observer = null;
+      themeObserver?.disconnect();
+      themeObserver = null;
+      term?.dispose();
+      term = null;
+      fitAddon = null;
+    });
+
+    // Live option updates (recreate-free where xterm supports it).
+    watch(
+      () => [props.fontSize, props.fontFamily, props.scrollback, props.cursorBlink],
+      ([fontSize, fontFamily, scrollback, cursorBlink]) => {
+        if (!term) return;
+        term.options.fontSize = fontSize as number;
+        term.options.fontFamily = fontFamily as string;
+        term.options.scrollback = scrollback as number;
+        term.options.cursorBlink = cursorBlink as boolean;
+        fitAddon?.fit();
+      },
+    );
+    watch(
+      () => [props.cols, props.rows],
+      ([cols, rows]) => {
+        if (!term) return;
+        if (term.cols !== (cols as number) || term.rows !== (rows as number)) {
+          // term.resize fires xterm's own onResize, which emits to the
+          // consumer exactly once — emitting here as well would double
+          // every resize.
+          term.resize(cols as number, rows as number);
+        }
+      },
+    );
+
+    expose({
+      /** Binary-safe feed: Uint8Array goes to xterm's UTF-8 decoder, so
+       * multi-byte sequences split across writes survive. */
+      write(data: string | Uint8Array) {
+        term?.write(data);
+      },
+      writeln(data: string) {
+        term?.writeln(data);
+      },
+      clear() {
+        term?.clear();
+      },
+      reset() {
+        term?.reset();
+      },
+      fit() {
+        fitAddon?.fit();
+      },
+      focus() {
+        term?.focus();
+      },
+      /** Current grid size (null before mount). */
+      get dimensions(): { cols: number; rows: number } | null {
+        return term ? { cols: term.cols, rows: term.rows } : null;
+      },
+    });
+
+    return () => <div ref={hostRef} class="hk-terminal" />;
+  },
+});
+
+/** Test seam: pure helpers (no DOM dependency beyond getComputedStyle). */
+export const __testables = { channelToHex };

package/src/index.ts

@@ -41,6 +41,7 @@ export { default as HLabel } from "./components/HkLabel";
 export { default as HListTransition } from "./components/HkListTransition";
 export { default as HLoadMore } from "./components/HkLoadMore";
 export { default as HMarkdownRenderer } from "./components/HkMarkdownRenderer";
+export { default as HTerminal } from "./components/HkTerminal";
 export { default as HModal } from "./components/HkModal";
 export { default as HNavItem } from "./components/HkNavItem";
 export { default as HNumberInput } from "./components/HkNumberInput";
@@ -688,6 +689,7 @@ export { default as HkDrawer } from "./components/HkDrawer";
 export { default as HkEmptyState } from "./components/HkEmptyState";
 export { default as HkExpansionPanel } from "./components/HkExpansionPanel";
 export { default as HkFab } from "./components/HkFab";
+export { default as HkFloatingLayer } from "./components/HkFloatingLayer";
 export { default as HkIcon } from "./components/HkIcon";
 export { default as HkIconButton } from "./components/HkIconButton";
 export { default as HkIconButtonGroup } from "./components/HkIconButtonGroup";
@@ -700,6 +702,7 @@ export { default as HkLabel } from "./components/HkLabel";
 export { default as HkListTransition } from "./components/HkListTransition";
 export { default as HkLoadMore } from "./components/HkLoadMore";
 export { default as HkMarkdownRenderer } from "./components/HkMarkdownRenderer";
+export { default as HkTerminal } from "./components/HkTerminal";
 export { default as HkModal } from "./components/HkModal";
 export { default as HkNavItem } from "./components/HkNavItem";
 export { default as HkNumberInput } from "./components/HkNumberInput";