@celestia-island/hikari 0.55.109 → 0.55.110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.109",
+  "version": "0.55.110",
   "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/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";
@@ -700,6 +701,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";