@celestia-island/hikari 0.39.0 → 0.40.1

package/package.json

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

package/src/components/HkAdaptiveDialog.tsx

@@ -38,7 +38,7 @@ import { useBreakpoint } from "../runtime/useBreakpoint";
 import "./HkAdaptiveDialog.scss";
 import HButton from "./HkButton";
 import HDrawer from "./HkDrawer";
-import HModal, { type ModalAction } from "./HkModal";
+import HModal, { type ModalAction, type ModalWidth } from "./HkModal";
 
 export default defineComponent({
   name: "HkAdaptiveDialog",
@@ -47,7 +47,7 @@ export default defineComponent({
     title: { type: String, default: undefined },
     closable: { type: Boolean, default: true },
     /** Desktop modal width (HkModal `width`). */
-    width: { type: String, default: "32rem" },
+    width: { type: String as PropType<ModalWidth>, default: "32rem" },
     /** Mobile drawer height (HkDrawer `size`). HkDrawer's bottom-side CSS
      *  clamps panels at maxHeight 70vh, so the default equals the cap;
      *  pass `panelClass` with a custom max-height for taller sheets. */

package/src/components/HkCaptchaModal.tsx

@@ -1,5 +1,5 @@
 import { defineComponent, type PropType } from "vue";
-import { HModal } from "@celestia-island/hikari";
+import { HModal, type ModalWidth } from "@celestia-island/hikari";
 
 import { useI18n } from "../i18n/context";
 
@@ -23,7 +23,7 @@ export const HkCaptchaModal = defineComponent({
     scriptUrl: { type: String, default: undefined },
     attempt: { type: Number, default: 0 },
     title: { type: String, default: undefined },
-    width: { type: String, default: "30rem" },
+    width: { type: String as PropType<ModalWidth>, default: "30rem" },
   },
   emits: {
     "update:modelValue": (_v: boolean) => true,

package/src/components/HkLogWindow.tsx

@@ -1,6 +1,6 @@
 import { computed, defineComponent, nextTick, ref, watch, type PropType } from "vue";
 import { Copy, Eraser, Pause, Play, ScrollText } from "lucide-vue-next";
-import { HModal, HScrollContainer, useClipboard } from "@celestia-island/hikari";
+import { HModal, HScrollContainer, useClipboard, type ModalWidth } from "@celestia-island/hikari";
 
 import { useI18n } from "../i18n/context";
 
@@ -47,7 +47,7 @@ export const HkLogWindow = defineComponent({
     /** Height of the log body (CSS length, e.g. "55vh"). */
     height: { type: String, default: "55vh" },
     title: { type: String, default: undefined },
-    width: { type: String, default: "60rem" },
+    width: { type: String as PropType<ModalWidth>, default: "60rem" },
   },
   emits: {
     "update:modelValue": (_v: boolean) => true,

package/src/components/HkModal.tsx

@@ -34,6 +34,84 @@ export interface ModalAction {
   onClick?: () => void;
 }
 
+/**
+ * Named width presets for the `width` prop. Callers kept reaching for
+ * semantic sizes (`width="sm"`) which, passed through as raw CSS
+ * `max-width`, are silently dropped by the browser — the frame fell back
+ * to `width: 100%` and spanned the whole viewport (chest #662-era change
+ * password modal rendered 2048px wide). Named values now resolve here;
+ * anything else keeps passing through as a CSS max-width value.
+ */
+export const MODAL_WIDTH_PRESETS = {
+  xs: "20rem",
+  sm: "32rem",
+  md: "40rem",
+  lg: "56rem",
+  xl: "72rem",
+} as const;
+
+export type ModalWidthPreset = keyof typeof MODAL_WIDTH_PRESETS;
+
+/**
+ * `width` accepts a named preset or any CSS max-width value. The
+ * `(string & {})` arm keeps preset autocomplete in TSX while still
+ * allowing arbitrary lengths ("32rem", "560px", "50%").
+ */
+export type ModalWidth = ModalWidthPreset | (string & {});
+
+const warnedWidths = new Set<string>();
+/** Dev-only warn-once memory cap: a session feeding dynamically generated
+ *  garbage widths must not grow the set forever. Prod never reaches this
+ *  code (DEV is statically false there). */
+const MAX_WARNED_WIDTHS = 50;
+
+/** Valid digit-free CSS max-width keywords: the browser honors these, so
+ *  the "would span the viewport" dev warn must stay silent for them. */
+const WIDTH_KEYWORDS = new Set([
+  "auto",
+  "none",
+  "min-content",
+  "max-content",
+  "fit-content",
+]);
+
+/**
+ * Resolve the `width` prop to a concrete CSS max-width value: presets map
+ * through `MODAL_WIDTH_PRESETS`, everything else passes through untouched.
+ * In dev, a value that is neither a preset, a keyword, nor a length (no
+ * digit anywhere — e.g. a stray token like `"wide"`) warns once: as a raw
+ * max-width it would be dropped by the browser and the modal would span
+ * the viewport.
+ */
+export function resolveModalWidth(width: string): string {
+  // Coerce defensively: a JS consumer passing width={560} skips the prop
+  // type check at runtime and Vue would have rendered the number as px.
+  const value = String(width);
+  // hasOwnProperty.call instead of Object.hasOwn (ES2022): the package
+  // ships TS source, so consumers' bundlers will not polyfill new
+  // built-ins — this must not raise the runtime floor. The own-property
+  // guard is what keeps inherited members ("constructor", "toString")
+  // from resolving as presets past the dev warn.
+  const key = value.trim();
+  const preset = Object.prototype.hasOwnProperty.call(MODAL_WIDTH_PRESETS, key)
+    ? MODAL_WIDTH_PRESETS[key as ModalWidthPreset]
+    : undefined;
+  if (preset !== undefined) return preset;
+  if (
+    import.meta.env?.DEV &&
+    !/\d/.test(value) &&
+    !WIDTH_KEYWORDS.has(key) &&
+    warnedWidths.size < MAX_WARNED_WIDTHS &&
+    !warnedWidths.has(value)
+  ) {
+    warnedWidths.add(value);
+    console.warn(
+      `[HkModal] width "${value}" is neither a named preset (${Object.keys(MODAL_WIDTH_PRESETS).join("/")}) nor a CSS length — the browser would drop it and the modal would span the viewport.`,
+    );
+  }
+  return value;
+}
+
 const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
@@ -44,7 +122,8 @@ export default defineComponent({
     modelValue: { type: Boolean, required: true },
     title: { type: String, default: undefined },
     closable: { type: Boolean, default: true },
-    width: { type: String, default: "32rem" },
+    /** Named preset ("xs"…"xl") or any CSS max-width value (see ModalWidth). */
+    width: { type: String as PropType<ModalWidth>, default: "32rem" },
     /**
      * Escape hatch: extra class appended to the .hk-modal-content frame
      * so hosts can restyle the surface without forking the modal (e.g.
@@ -114,7 +193,7 @@ export default defineComponent({
 
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
     const contentZ = computed(() => (handle.value?.zIndex ?? 0) + 1);
-    const resolvedWidth = computed(() => props.width);
+    const resolvedWidth = computed(() => resolveModalWidth(props.width));
     // Layer/dialog name: the explicit surface name wins over the header
     // title (which header-less surfaces never pass).
     const resolvedSurfaceName = computed(() => props.surfaceTitle ?? props.title);

package/src/components/HkModal.width.test.tsx

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkModal, { MODAL_WIDTH_PRESETS, resolveModalWidth } from "./HkModal";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(async () => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  vi.restoreAllMocks();
+});
+
+describe("resolveModalWidth", () => {
+  it("maps every named preset to its CSS max-width value", () => {
+    for (const [name, css] of Object.entries(MODAL_WIDTH_PRESETS)) {
+      expect(resolveModalWidth(name)).toBe(css);
+    }
+  });
+
+  it("keeps the default-sized presets bounded and ordered", () => {
+    // Sanity on the scale itself: xs < sm(default) < md < lg < xl.
+    expect(MODAL_WIDTH_PRESETS.xs).toBe("20rem");
+    expect(MODAL_WIDTH_PRESETS.sm).toBe("32rem");
+    expect(MODAL_WIDTH_PRESETS.md).toBe("40rem");
+    expect(MODAL_WIDTH_PRESETS.lg).toBe("56rem");
+    expect(MODAL_WIDTH_PRESETS.xl).toBe("72rem");
+  });
+
+  it("passes arbitrary CSS max-width values through untouched", () => {
+    expect(resolveModalWidth("32rem")).toBe("32rem");
+    expect(resolveModalWidth("560px")).toBe("560px");
+    expect(resolveModalWidth("50%")).toBe("50%");
+    expect(resolveModalWidth("min(90vw, 48rem)")).toBe("min(90vw, 48rem)");
+  });
+
+  it("passes digit-free max-width keywords through without warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    for (const keyword of ["auto", "none", "min-content", "max-content", "fit-content"]) {
+      expect(resolveModalWidth(keyword)).toBe(keyword);
+    }
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("coerces a numeric width from JS consumers instead of throwing", () => {
+    expect(resolveModalWidth(560 as unknown as string)).toBe("560");
+  });
+
+  it("does not inherit Object.prototype members as presets", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // A bare index lookup would resolve "constructor"/"toString" to
+    // inherited functions and early-return them past the warn — the
+    // guard must treat them as unknown values instead.
+    for (const hostile of ["constructor", "toString", "valueOf"]) {
+      expect(resolveModalWidth(hostile)).toBe(hostile);
+    }
+    expect(warn).toHaveBeenCalledTimes(3);
+  });
+
+  it("trims surrounding whitespace before the preset lookup", () => {
+    expect(resolveModalWidth(" sm ")).toBe("32rem");
+    expect(resolveModalWidth(" 560px ")).toBe(" 560px ");
+  });
+
+  it("warns once in dev for a value that is neither a preset nor a length", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // A unique digit-free token per run: the warn-once set is module
+    // state, and any digit would classify the value as a length.
+    const stray = `wide-${Math.random().toString(36).slice(2).replace(/\d/g, "") || "wide"}`;
+    expect(resolveModalWidth(stray)).toBe(stray);
+    expect(resolveModalWidth(stray)).toBe(stray);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toContain(stray);
+  });
+});
+
+describe("HkModal width rendering", () => {
+  async function mountModal(width: string): Promise<HTMLElement> {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const open = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, {
+            modelValue: open.value,
+            width,
+          }, { default: () => h("div", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await nextTick();
+
+    // HkModal Teleports to document.body — the mount container stays empty.
+    const content = document.body.querySelector<HTMLElement>(".hk-modal-content");
+    expect(content).toBeTruthy();
+    return content!;
+  }
+
+  it("renders a named preset as the frame's max-width", async () => {
+    const content = await mountModal("sm");
+    expect(content.style.maxWidth).toBe("32rem");
+  });
+
+  it("renders an arbitrary CSS length as the frame's max-width", async () => {
+    const content = await mountModal("560px");
+    expect(content.style.maxWidth).toBe("560px");
+  });
+});

package/src/components/HkProtocolModal.tsx

@@ -1,5 +1,5 @@
-import { computed, defineComponent, onBeforeUnmount, ref, watch } from "vue";
-import { HMarkdownRenderer, HModal, useClipboard, type ModalAction } from "@celestia-island/hikari";
+import { computed, defineComponent, onBeforeUnmount, ref, watch, type PropType } from "vue";
+import { HMarkdownRenderer, HModal, useClipboard, type ModalAction, type ModalWidth } from "@celestia-island/hikari";
 
 import { useI18n } from "../i18n/context";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
@@ -29,7 +29,7 @@ export const HkProtocolModal = defineComponent({
     declineLabel: { type: String, default: undefined },
     /** Allow dismissing without a decision (overlay/ESC/X). Default true. */
     closable: { type: Boolean, default: true },
-    width: { type: String, default: "48rem" },
+    width: { type: String as PropType<ModalWidth>, default: "48rem" },
     /** Cap the scroll body height (e.g. "60vh"). */
     bodyHeight: { type: String, default: undefined },
   },

package/src/components/HkTitleBar.scss

@@ -0,0 +1,128 @@
+// HkTitleBar — hybrid-shell caption bar.
+//
+// Colors ride the theme channels (--color-*) so the bar follows whatever
+// preset/mode the host app is in. Drag is pure CSS app-region (Tauri and
+// Electron both honor it); interactive children opt out with no-drag.
+// Text selection is chrome-disabled across the whole bar.
+
+.hk-titlebar {
+  --hk-tb-height: 32px;
+  --hk-tb-bg: color-mix(in srgb, rgb(var(--color-surface, 240 244 248)) 80%, transparent);
+  --hk-tb-border: rgb(var(--color-border, 100 100 100) / 0.25);
+  --hk-tb-fg: rgb(var(--color-text-secondary, 102 102 102));
+  --hk-tb-fg-strong: rgb(var(--color-text, 30 30 30));
+  --hk-tb-hover: rgb(var(--color-primary, 122 162 247) / 0.12);
+  --hk-tb-active: rgb(var(--color-primary, 122 162 247) / 0.2);
+  --hk-tb-focus: rgb(var(--color-primary, 122 162 247) / 0.6);
+  --hk-tb-close-hover: #e81123;
+  --hk-tb-close-active: #f1707a;
+  --hk-tb-radius-close: 0 8px 0 0;
+
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: var(--hk-tb-height);
+  display: flex;
+  align-items: center;
+  z-index: var(--z-titlebar, 100001);
+  user-select: none;
+  -webkit-user-select: none;
+  background: var(--hk-tb-bg);
+  backdrop-filter: blur(16px);
+  border-bottom: 1px solid var(--hk-tb-border);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  -webkit-app-region: drag;
+  app-region: drag;
+}
+
+.hk-titlebar-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding-left: 12px;
+  white-space: nowrap;
+  cursor: default;
+}
+
+.hk-titlebar-icon {
+  width: 16px;
+  height: 16px;
+  display: block;
+  pointer-events: none;
+}
+
+.hk-titlebar-title-text {
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  color: var(--hk-tb-fg-strong);
+}
+
+.hk-titlebar-subtitle {
+  font-size: 10px;
+  color: var(--hk-tb-fg);
+  opacity: 0.7;
+  padding-left: 8px;
+  white-space: nowrap;
+}
+
+.hk-titlebar-spacer {
+  flex: 1;
+}
+
+.hk-titlebar-actions {
+  -webkit-app-region: no-drag;
+  app-region: no-drag;
+  display: flex;
+  align-items: center;
+  height: 100%;
+}
+
+.hk-titlebar-btn {
+  width: 46px;
+  height: var(--hk-tb-height);
+  border: none;
+  background: transparent;
+  color: var(--hk-tb-fg);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background-color 0.12s ease, color 0.12s ease;
+  outline: none;
+  padding: 0;
+}
+
+.hk-titlebar-btn:hover {
+  background: var(--hk-tb-hover);
+  color: var(--hk-tb-fg-strong);
+}
+
+.hk-titlebar-btn:active {
+  background: var(--hk-tb-active);
+}
+
+/* Only the rightmost (close) button carries the window's top-right
+   corner radius; the other captions highlight as plain rectangles. */
+.hk-titlebar-btn-close {
+  border-radius: 0 8px 0 0;
+}
+
+.hk-titlebar-btn-close:hover {
+  background: var(--hk-tb-close-hover);
+  color: #fff;
+}
+
+.hk-titlebar-btn-close:active {
+  background: var(--hk-tb-close-active);
+  color: #fff;
+}
+
+.hk-titlebar-btn:focus-visible {
+  outline: 2px solid var(--hk-tb-focus);
+  outline-offset: -2px;
+}
+
+/* Host apps offset their own root container below the bar:
+   #app { position: absolute; top: var(--hk-tb-height); … } */

package/src/components/HkTitleBar.tsx

@@ -0,0 +1,132 @@
+import { defineComponent, onBeforeUnmount, onMounted, ref } from "vue";
+
+import "./HkTitleBar.scss";
+
+/**
+ * HkTitleBar — hybrid-shell window caption bar.
+ *
+ * A pure visual + event component: it renders the bar (app icon, title,
+ * subtitle, draggable surface, right-side caption buttons) and EMITS
+ * `minimize` / `toggle-maximize` / `close` / custom-button clicks. It
+ * never touches a shell API itself — the host (Tauri, Electron, …) wires
+ * those events to its own window controls, keeping hikari dependency-free.
+ *
+ * Dragging is pure CSS (`app-region: drag` on the bar, `no-drag` on the
+ * interactive children) — supported by Tauri (WebView2/WKWebView/WebKitGTK)
+ * and Electron alike; no JS drag logic needed.
+ *
+ * Text selection is disabled across the bar (captions are chrome, not
+ * content).
+ *
+ * Buttons are selective: `showMinimize` / `showMaximize` / `showClose`
+ * (defaults true/true/true) and `customActions` render extra icon buttons
+ * to the LEFT of minimize, each emitting `action` with its id.
+ *
+ * The maximized state is data-driven: the host passes `maximized` and the
+ * component swaps the maximize/restore glyph — no shell probing inside.
+ */
+export default defineComponent({
+  name: "HkTitleBar",
+  props: {
+    title: { type: String, default: "" },
+    subtitle: { type: String, default: "" },
+    /** App icon rendered left of the title (img src or inline node). */
+    icon: { type: String, default: "" },
+    maximized: { type: Boolean, default: false },
+    showMinimize: { type: Boolean, default: true },
+    showMaximize: { type: Boolean, default: true },
+    showClose: { type: Boolean, default: true },
+    /** Extra icon buttons rendered left of minimize. */
+    customActions: {
+      type: Array as () => { id: string; label: string; icon?: unknown }[],
+      default: () => [],
+    },
+  },
+  emits: {
+    minimize: () => true,
+    "toggle-maximize": () => true,
+    close: () => true,
+    /** A custom action button was clicked (id from `customActions`). */
+    action: (_id: string) => true,
+  },
+  setup(props, { emit, slots }) {
+    return () => (
+      <div class="hk-titlebar" data-drag-region>
+        {slots.left?.() ?? (
+          <span class="hk-titlebar-title">
+            {props.icon && <img class="hk-titlebar-icon" src={props.icon} alt="" />}
+            <span class="hk-titlebar-title-text">{props.title}</span>
+            {props.subtitle && (
+              <span class="hk-titlebar-subtitle">{props.subtitle}</span>
+            )}
+          </span>
+        )}
+        <span class="hk-titlebar-spacer" />
+        <div class="hk-titlebar-actions">
+          {slots.actions?.()}
+          {props.customActions.map((a) => (
+            <button
+              key={a.id}
+              type="button"
+              class="hk-titlebar-btn"
+              title={a.label}
+              aria-label={a.label}
+              onClick={(e: MouseEvent) => {
+                e.stopPropagation();
+                emit("action", a.id);
+              }}
+            >
+              {a.icon}
+            </button>
+          ))}
+          {props.showMinimize && (
+            <button
+              type="button"
+              class="hk-titlebar-btn"
+              title="Minimize"
+              aria-label="Minimize"
+              onClick={(e: MouseEvent) => {
+                e.stopPropagation();
+                emit("minimize");
+              }}
+            >
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round"><path d="M5 12h14" /></svg>
+            </button>
+          )}
+          {props.showMaximize && (
+            <button
+              type="button"
+              class="hk-titlebar-btn"
+              title={props.maximized ? "Restore" : "Maximize"}
+              aria-label={props.maximized ? "Restore" : "Maximize"}
+              onClick={(e: MouseEvent) => {
+                e.stopPropagation();
+                emit("toggle-maximize");
+              }}
+            >
+              {props.maximized ? (
+                <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75"><rect x="3" y="8" width="13" height="13" rx="2" /><path d="M8 8V5a2 2 0 0 1 2-2h11a2 2 0 0 1 2 2v11a2 2 0 0 1-2 2h-3" /></svg>
+              ) : (
+                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75"><rect x="4" y="4" width="16" height="16" rx="2" /></svg>
+              )}
+            </button>
+          )}
+          {props.showClose && (
+            <button
+              type="button"
+              class="hk-titlebar-btn hk-titlebar-btn-close"
+              title="Close"
+              aria-label="Close"
+              onClick={(e: MouseEvent) => {
+                e.stopPropagation();
+                emit("close");
+              }}
+            >
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18" /></svg>
+            </button>
+          )}
+        </div>
+      </div>
+    );
+  },
+});

package/src/index.ts

@@ -79,6 +79,7 @@ export { default as HWindowedItem } from "./components/HkWindowedItem";
 export { default as HDateTimePicker } from "./components/HkDateTimePicker";
 export { default as HDatePicker } from "./components/HkDatePicker";
 export { default as HTimeline } from "./components/HkTimeline";
+export { default as HTitleBar } from "./components/HkTitleBar";
 export { default as HStepFlow } from "./components/HkStepFlow";
 export type { StepFlowSlotProps } from "./components/HkStepFlow";
 
@@ -114,6 +115,11 @@ export { type BoardNodeInput, type BoardEdgeInput } from "./components/HkBoard";
 export { type BoardAnchorMode, type BoardEdgeStyle, type BoardPoint } from "./utils/boardEdges";
 export { type BoardCamera, type BoardRect, type BoardViewport } from "./utils/boardCamera";
 export { type ModalAction } from "./components/HkModal";
+export {
+  type ModalWidth,
+  type ModalWidthPreset,
+  resolveModalWidth,
+} from "./components/HkModal";
 export { type TreeNode, type TreeSize, type TreeRowScope } from "./components/HkTree";
 export { type DragListItem } from "./components/HkDraggableList";
 export { type GridItem } from "./components/HkDraggableGrid";

package/src/styles/theme/channels.scss

@@ -0,0 +1,162 @@
+// Vendored from packages/vue/src/tokens.scss so npm registry installs can
+// resolve it — the exports map only exposes ./styles/*, and consumers that
+// build their own shell (non-chest webuis) need the --color-* channel
+// defaults + resolved --hi-* aliases at CSS level, before the runtime
+// (initTheme) injects inline overrides. Edit the upstream file, then
+// re-copy; do not hand-edit here.
+
+/* ── Syntax highlighting palette family: --code-* ───────────────────
+ * Token names consumed by hikari's highlighted-code surfaces (the
+ * HkToolBlock syntax layer and its JSON viewer, see HkToolBlock.scss).
+ * The VALUES are intentionally NOT defined here: the family is owned by
+ * the host theme, which maps each token to mode-aware colors. The
+ * canonical mapping (dark = One Dark, light = GitHub Light) lives in the
+ * celestia webui theme.scss; components reference the tokens with their
+ * original One Dark values as fallbacks so standalone consumers render
+ * unchanged. Extend this family only by adding a --code-* token with a
+ * fallback equal to the current visual.
+ *   --code-keyword  hljs-keyword / selector-tag       (purple)
+ *   --code-builtin  hljs-built_in                     (purple → blue in light)
+ *   --code-string   hljs-string                       (green)
+ *   --code-number   hljs-number / literal / attr      (orange → blue in light)
+ *   --code-comment  hljs-comment / doctag             (grey, italic)
+ *   --code-function hljs-title.function_              (blue)
+ *   --code-type     hljs-type / class title           (yellow → green in light)
+ *   --code-variable hljs-variable / template-var      (red → orange in light)
+ */
+/* hikari color aliases — fallback values for theme tokens.
+   These CSS variables are used by hikari components (HkButton, HkCard,
+   HkInput, HkSelect, etc.) and are expected to be overridden by
+   consuming apps via initTheme() or custom theme CSS. */
+:root {
+  --c-primary-faint: rgb(var(--color-primary, 122 162 247) / 5%);
+  --c-primary-subtle: rgb(var(--color-primary, 122 162 247) / 8%);
+  --c-primary-dim: rgb(var(--color-primary, 122 162 247) / 10%);
+  --c-primary-light: rgb(var(--color-primary, 122 162 247) / 15%);
+  --c-primary-overlay: rgb(var(--color-primary, 122 162 247) / 15%);
+  --c-primary-medium: rgb(var(--color-primary, 122 162 247) / 25%);
+  --c-primary-strong: rgb(var(--color-primary, 122 162 247) / 40%);
+  --c-primary-intense: rgb(var(--color-primary, 122 162 247) / 40%);
+  --c-error-dim: rgb(var(--color-error, 247 118 142) / 10%);
+  --c-error-overlay: rgb(var(--color-error, 247 118 142) / 20%);
+  --c-error-strong: rgb(var(--color-error, 247 118 142) / 50%);
+  --shadow-elevated: 0 8px 32px rgb(0 0 0 / 15%);
+  --shadow-dropdown: 0 4px 24px rgb(0 0 0 / 12%), 0 0 0 1px rgb(255 255 255 / 4%);
+  --shadow-button: 0 4px 14px rgb(var(--color-primary, 122 162 247) / 35%);
+  --shadow-button-danger: 0 4px 14px rgb(var(--color-error, 247 118 142) / 35%);
+  --shadow-focus: 0 0 0 3px rgb(var(--color-primary, 122 162 247) / 12%);
+  --shadow-focus-error: 0 0 0 3px rgb(var(--color-error, 247 118 142) / 12%);
+  --border-input: rgb(var(--color-border, 100 100 100) / 15%);
+  --border-faint: rgb(var(--color-border, 100 100 100) / 10%);
+  --border-subtle: rgb(var(--color-border, 100 100 100) / 12%);
+
+  /* Icon-button state bridge — HkIconButtonVars references this vocabulary
+     but nothing ever defined it, so every var() without an in-file fallback
+     was invalid at computed-value time: non-ghost variants had no active
+     background, focus rings and glow vanished, and one missing item even
+     invalidated the whole transition shorthand (all icon buttons lost their
+     hover/press animation). Defined once here as live expressions over the
+     theme triplets so they track whichever palette is active; the -dark
+     variants are the pressed-step of their base slot. */
+  --hi-icon-color: rgb(var(--color-text, 30 30 30));
+  --hi-icon-size-xs: 0.75rem;
+  --hi-icon-size-sm: 1rem;
+  --hi-icon-size-md: 1.25rem;
+  --hi-icon-size-lg: 1.5rem;
+  --hi-duration-instant: var(--duration-instant, 0.1s);
+  --hi-border-color-focus: rgb(var(--color-primary, 122 162 247));
+  --hi-glow-color: transparent;
+  --hi-bg-surface-dark: rgb(var(--color-muted, 108 108 108) / 12%);
+  --hi-color-primary-dark: color-mix(in srgb, rgb(var(--color-primary, 122 162 247)) 82%, #000);
+  --hi-color-secondary-dark: color-mix(in srgb, rgb(var(--color-secondary, 81 154 115)) 82%, #000);
+  --hi-color-danger-dark: color-mix(in srgb, rgb(var(--color-error, 200 50 50)) 82%, #000);
+  --hi-color-success-dark: color-mix(in srgb, rgb(var(--color-success, 0 150 0)) 82%, #000);
+  --hi-color-text-on-secondary: rgb(var(--color-on-solid, 255 255 255));
+  --hi-color-text-on-danger: rgb(var(--color-on-solid, 255 255 255));
+  --hi-color-text-on-success: rgb(var(--color-on-solid, 255 255 255));
+}
+
+/* Static default light theme — renders correctly even without initTheme().
+   initTheme() overrides these at runtime via inline styles on
+   documentElement, which beat stylesheet :root declarations. */
+:root {
+  --color-primary: 122 162 247;
+  --color-on-primary: 255 255 255;
+  --color-on-solid: 255 255 255;
+  --color-on-solid-text: 255 255 255;
+  --color-on-solid-icon: 255 255 255;
+  --color-secondary: 81 154 115;
+  --color-accent: 247 181 0;
+  --color-text: 30 30 30;
+  --color-text-secondary: 102 102 102;
+  --color-text-tertiary: 140 140 140;
+  --color-muted: 108 108 108;
+  --color-border: 100 100 100;
+  --color-focused-border: 122 162 247;
+  --color-background: 214 236 240;
+  --color-surface: 240 244 248;
+  --color-success: 14 184 64;
+  --color-error: 247 118 142;
+  --color-warning: 238 214 119;
+  --color-info: 106 190 214;
+
+  --hi-color-primary: rgb(var(--color-primary));
+  --hi-color-secondary: rgb(var(--color-secondary));
+  --hi-color-surface: rgb(var(--color-surface));
+  --hi-color-background: rgb(var(--color-background));
+  --hi-color-border: rgb(var(--color-border));
+  --hi-color-text-primary: rgb(var(--color-text));
+  --hi-color-text-secondary: rgb(var(--color-text-secondary));
+  --hi-color-muted: rgb(var(--color-muted));
+  --hi-color-on-primary: rgb(var(--color-on-primary));
+  /* Deprecated in-tree: luminance-computed contrast, kept only for external
+     consumers. In-tree components use the on-solid slots instead. */
+  --hi-color-text-on-primary: rgb(var(--color-on-primary));
+  --hi-color-text-on-solid: rgb(var(--color-on-solid-text, 255 255 255));
+  --hi-color-icon-on-solid: rgb(var(--color-on-solid-icon, 255 255 255));
+  --hi-color-success: rgb(var(--color-success));
+  --hi-color-error: rgb(var(--color-error));
+  --hi-color-warning: rgb(var(--color-warning));
+  --hi-color-info: rgb(var(--color-info));
+
+  /* Design tokens consumed by hikari components. These used to live only in
+     plana-ui's token set; without them the background/backdrop declarations
+     of fields and surfaces resolve to nothing. Values align with plana-ui. */
+  --space-2: 0.125rem;
+  --space-4: 0.25rem;
+  --space-6: 0.375rem;
+  --space-8: 0.5rem;
+  --space-10: 0.625rem;
+  --space-12: 0.75rem;
+  --space-14: 0.875rem;
+  --space-16: 1rem;
+  --space-20: 1.25rem;
+  --space-24: 1.5rem;
+  --space-28: 1.75rem;
+  --space-32: 2rem;
+  --space-40: 2.5rem;
+  --text-2xs: 0.625rem;
+  --text-xs: 0.75rem;
+  --text-sm: 0.8125rem;
+  --text-base: 0.875rem;
+  --text-md: 1rem;
+  --text-lg: 1.125rem;
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --opacity-half: 0.92;
+  --blur-sm: 8px;
+  --blur-md: 16px;
+  --blur-lg: 24px;
+  --duration-fast: 0.15s;
+  --duration-short: 0.15s;
+  --duration-normal: 0.3s;
+  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
+  --ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
+  --s-footer-height: 3rem;
+  --z-header: 30;
+  --z-sidebar: 40;
+  /* Apple-style stack + CJK UI tail — keep in sync with packages/vue/src/theme/fontContext.ts */
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
+  --font-reading: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
+}