@celestia-island/hikari 0.55.203 → 0.55.205

package/package.json

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

package/src/components/HkAdminHeader.tsx

@@ -20,6 +20,14 @@ export const HkAdminHeader = defineComponent({
     title: { type: String, default: "" },
     showHamburger: { type: Boolean, default: false },
     compact: { type: Boolean, default: false },
+    /** Desktop shell face whose header IS the window title bar (Tauri
+     *  decorations:false): pass true iff the header renders the
+     *  HkWindowControls cluster, so the right inset follows the
+     *  window-controls chrome contract (.s-glass-header--chrome /
+     *  --hk-window-controls-edge-inset) instead of the content inset —
+     *  a standard-mode cluster glued to the frame corner is the flush
+     *  variant's look worn by the wrong mode (field report 2026-10-25). */
+    chrome: { type: Boolean, default: false },
     actions: { type: Array as PropType<VNode[]>, default: () => [] },
     /** Signed-in identity. Drives the avatar fallback letter, the
      *  dropdown identity block and the pending-state branch — it is
@@ -192,6 +200,7 @@ export const HkAdminHeader = defineComponent({
           "s-glass-header",
           "s-balanced-header",
           props.compact ? "s-glass-header--compact" : "",
+          props.chrome ? "s-glass-header--chrome" : "",
         ]}
       >
         <div ref={userTriggerRef} class="s-admin-header-user s-header-wing-start">

package/src/components/HkMarkdownRenderer.scss

@@ -78,6 +78,43 @@
   margin: 0;
 }
 
+/* Markdown tables size to their content, so a wide one (many columns, or
+   a single unbreakable cell) pushes every ancestor's min-content width
+   past its box — clipping hosts (the modal reading region, chat bubbles,
+   report cards) then leave the far columns unreachable. The renderer wraps
+   every table in the same two-level shape as code above: this wrap is the
+   rail HOST (track host for the scroller below — it contains ONLY the
+   scrolling box, so the rail hugs the table instead of spanning the whole
+   markdown body, useOverlayScrollbar's host contract) and carries the
+   table's vertical margin, because a scroll container never collapses
+   margins with its children and the margin must keep collapsing with the
+   surrounding flow exactly as the bare table's did. */
+.hk-md-table-wrap {
+  position: relative;
+  margin: 0.75em 0;
+}
+
+/* The horizontal rail itself — the viewport the overlay scrollbar attaches
+   to. Only a genuinely overflowing table grows the scroll; normal tables
+   keep their full-width layout. Same hidden-native-chrome contract as
+   .hk-md-code (the 2026-10-01 native-bar regression rule). */
+.hk-md-table-scroll {
+  overflow-x: auto;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+/* The railed table renders flush inside its scroller — its old vertical
+   margin lives on the host wrap above. Outranks `.hk-markdown table`
+   (two classes + one type vs one class + one type); GFM tables cannot
+   nest, so no other table is ever matched. */
+.hk-markdown .hk-md-table-wrap table {
+  margin: 0;
+}
+
 .hk-md-code-lang {
   position: absolute;
   top: 0.25em;

package/src/components/HkMarkdownRenderer.tsx

@@ -61,7 +61,8 @@ async function renderMarkdown(content: string): Promise<string> {
     return renderPlain(content);
   }
 
-  const renderer = new (marked as unknown as { Renderer: new () => Record<string, unknown> }).Renderer();
+  const RendererCtor = (marked as unknown as { Renderer: new () => Record<string, unknown> }).Renderer;
+  const renderer = new RendererCtor();
 
   (renderer as Record<string, unknown>).code = function (tok: { text: string; lang?: string }) {
     const highlighted = tryHighlight(tok.text, tok.lang);
@@ -74,6 +75,21 @@ async function renderMarkdown(content: string): Promise<string> {
     return `<div class="hk-md-code-wrap"><div class="hk-md-code">${langLabel}<pre><code class="hljs${langAttr}">${highlighted}</code></pre></div></div>`;
   };
 
+  (renderer as Record<string, unknown>).table = function (token: unknown) {
+    // Tables size to their content: a wide one (many columns, or a single
+    // unbreakable cell) pushes every ancestor's min-content width past its
+    // box, and clipping hosts (modal reading region, chat bubbles, report
+    // cards) leave the far columns unreachable. Same two-level shape as the
+    // code override above: `.hk-md-table-wrap` is the rail HOST (a plain
+    // positioned box wrapping only the scroller — the engine anchors the
+    // track in the viewport's parent), `.hk-md-table-scroll` is the
+    // viewport that actually rails. Rail the TABLE itself — normal tables
+    // keep their full-width layout; only a genuinely overflowing one grows
+    // the horizontal scroll (see .hk-md-table-scroll).
+    const inner = (RendererCtor.prototype as { table: (t: unknown) => string }).table.call(this, token);
+    return `<div class="hk-md-table-wrap"><div class="hk-md-table-scroll">${inner}</div></div>`;
+  };
+
   const raw = marked.parse(content, { renderer, async: false });
   const html = typeof raw === "string" ? raw : "";
   return DOMPurify.sanitize(html);
@@ -114,33 +130,34 @@ export default defineComponent({
       { immediate: true },
     );
 
-    // Overlay scrollbars (shared chrome) on markdown code blocks. The
-    // body is innerHTML-rendered and fully replaced on every parse, so
-    // the attachment set is reconciled after each render pass: handles
-    // whose block left the DOM detach, fresh blocks attach.
+    // Overlay scrollbars (shared chrome) on the markdown blocks that can
+    // rail horizontally: code blocks and table scrollers. The body is
+    // innerHTML-rendered and fully replaced on every parse, so the
+    // attachment set is reconciled after each render pass: handles whose
+    // block left the DOM detach, fresh blocks attach.
     const bodyRef = ref<HTMLElement>();
-    const codeScrollbars: Array<{ el: HTMLElement; handle: OverlayScrollbarHandle }> = [];
+    const overlayScrollbars: Array<{ el: HTMLElement; handle: OverlayScrollbarHandle }> = [];
 
-    function syncCodeScrollbars() {
-      for (let i = codeScrollbars.length - 1; i >= 0; i--) {
-        if (!codeScrollbars[i].el.isConnected) {
-          codeScrollbars[i].handle.detach();
-          codeScrollbars.splice(i, 1);
+    function syncOverlayScrollbars() {
+      for (let i = overlayScrollbars.length - 1; i >= 0; i--) {
+        if (!overlayScrollbars[i].el.isConnected) {
+          overlayScrollbars[i].handle.detach();
+          overlayScrollbars.splice(i, 1);
         }
       }
-      for (const el of bodyRef.value?.querySelectorAll<HTMLElement>(".hk-md-code") ?? []) {
-        if (codeScrollbars.some((c) => c.el === el)) continue;
-        codeScrollbars.push({ el, handle: attachOverlayScrollbars(el, { axis: "horizontal" }) });
+      for (const el of bodyRef.value?.querySelectorAll<HTMLElement>(".hk-md-code, .hk-md-table-scroll") ?? []) {
+        if (overlayScrollbars.some((c) => c.el === el)) continue;
+        overlayScrollbars.push({ el, handle: attachOverlayScrollbars(el, { axis: "horizontal" }) });
       }
     }
 
     watch(renderedHtml, () => {
-      void nextTick(syncCodeScrollbars);
+      void nextTick(syncOverlayScrollbars);
     });
 
     onBeforeUnmount(() => {
-      for (const c of codeScrollbars) c.handle.detach();
-      codeScrollbars.length = 0;
+      for (const c of overlayScrollbars) c.handle.detach();
+      overlayScrollbars.length = 0;
     });
 
     return () => (

package/src/components/HkWindowControls.scss

@@ -3,7 +3,12 @@
 // standard: borderless ghost buttons at the header chrome's own size
 // step (2rem boxes, 16px glyphs, 0.375rem gaps) — no borders, no
 // dividers, no container chrome; the close hover is a small rounded
-// red wash. Reads as one family with gear/search icon buttons.
+// red wash. Reads as one family with gear/search icon buttons. The
+// HOST keeps the canonical right edge inset
+// (--hk-window-controls-edge-inset, declared in styles/admin-tokens)
+// — a standard cluster never rides the frame; gluing it to the corner
+// is the flush mode's look worn by the wrong mode (field report
+// 2026-10-25: the chest login strip had no right padding at all).
 //
 // flush: edge-riding squares for thin captions — the host zeroes its
 // own right padding (the s-header-bar--chrome contract pattern); the

package/src/components/HkWindowControls.tsx

@@ -15,6 +15,17 @@ import "./HkWindowControls.scss";
  *   with comfortable gaps. The whole top-right reads as one family of
  *   identical buttons; the close hover is a small rounded red wash.
  *   THE mode for content-height headers (3rem-class bars).
+ *   HOST CONTRACT: this mode never rides the window edge (that is the
+ *   flush variant's job) — the host keeps the canonical inset
+ *   `var(--hk-window-controls-edge-inset)` (≤1023px:
+ *   `--hk-window-controls-edge-inset-compact`) between the cluster
+ *   and the frame — token values live once in styles/admin-tokens,
+ *   not restated here. A standard cluster glued to the frame corner
+ *   is the wrong mode's look (field report 2026-10-25: the chest
+ *   login strip rendered with no end padding at all);
+ *   `.s-glass-header--chrome` is the in-library implementation of the
+ *   contract for admin headers, and the chat face sources its
+ *   `--chrome` padding from the same tokens.
  *
  * - `flush` — edge-riding squares that fill the host's height (the
  *   host must zero its own right padding so the close button rides

package/src/components/__tests__/hkMarkdownTableWrap.test.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Source contract for the markdown table rail (2026-10-24: a wide table —
+ * many columns or one unbreakable cell — pushed every ancestor's
+ * min-content width past its box, and clipping hosts (the chest report
+ * modal's reading region, chat bubbles, report cards) left the far columns
+ * unreachable).
+ *
+ * vitest never resolves stylesheets, and the renderer's marked/DOMPurify
+ * are lazy dynamic imports, so this pins the moving parts as source
+ * contracts in the same idiom as hkMarkdownLang.test.ts:
+ *
+ *   - the renderer overrides `table` to wrap the emitted table in the
+ *     two-level rail shape (host + scroller), delegating to the base
+ *     Renderer for the table markup itself;
+ *   - the stylesheet gives the scroller the horizontal rail with the
+ *     hidden-native-chrome contract (the 2026-10-01 native-bar rule) and
+ *     makes the wrap a positioned rail host carrying the vertical margin;
+ *   - the overlay-scrollbar reconciliation covers the scroller alongside
+ *     `.hk-md-code`, so the rail gets the shared chrome and detaches with
+ *     the block.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const tsx = readFileSync(join(here, "../HkMarkdownRenderer.tsx"), "utf-8");
+const scss = readFileSync(join(here, "../HkMarkdownRenderer.scss"), "utf-8");
+
+describe("markdown table rail contract", () => {
+  it("the renderer wraps tables in the rail via the base renderer", () => {
+    // The override must DELEGATE (base table markup) and then wrap — a
+    // replacement that dropped the delegation would lose marked's table
+    // rendering; a wrap without the override is the dead-selector shape.
+    // The wrap is TWO-level (`.hk-md-table-wrap` host containing the
+    // `.hk-md-table-scroll` viewport): the overlay engine anchors its
+    // track in the viewport's PARENT, so a single-level wrap would rail
+    // against the whole `.hk-markdown-body` instead of the table.
+    expect(tsx).toMatch(
+      /return\s*`<div class="hk-md-table-wrap"><div class="hk-md-table-scroll">\$\{inner\}<\/div><\/div>`;/,
+    );
+    expect(tsx).toMatch(
+      /RendererCtor\.prototype as \{ table: \(t: unknown\) => string \}\)\.table\.call\(this, token\)/,
+    );
+  });
+
+  it("the rail stylesheet keeps native chrome hidden on the scroller", () => {
+    expect(scss).toMatch(
+      /\.hk-md-table-scroll\s*\{[^}]*overflow-x:\s*auto/,
+    );
+    expect(scss).toMatch(
+      /\.hk-md-table-scroll\s*\{[^}]*scrollbar-width:\s*none/,
+    );
+  });
+
+  it("the wrap is a positioned host carrying the table's vertical margin", () => {
+    // Host: wraps ONLY the scroller and is positioned, so the rail hugs
+    // the table (no guard promotion of `.hk-markdown-body`); the margin
+    // lives here because the scroll box never collapses margins with its
+    // children — this keeps normal tables' surrounding rhythm identical
+    // to the pre-wrap bare table.
+    expect(scss).toMatch(
+      /\.hk-md-table-wrap\s*\{[^}]*position:\s*relative/,
+    );
+    expect(scss).toMatch(
+      /\.hk-md-table-wrap\s*\{[^}]*margin:\s*0\.75em\s+0/,
+    );
+    expect(scss).toMatch(
+      // `0\s*;` — a bare `margin:\s*0` would also prefix-match the
+      // bare-table `margin: 0.75em 0` and false-pass the very double-margin
+      // regression this reset exists to prevent.
+      /\.hk-markdown \.hk-md-table-wrap table\s*\{[^}]*margin:\s*0\s*;/,
+    );
+  });
+
+  it("the overlay reconciliation covers the rail alongside code blocks", () => {
+    expect(tsx).toMatch(
+      /querySelectorAll<HTMLElement>\("\.hk-md-code, \.hk-md-table-scroll"\)/,
+    );
+  });
+});

package/src/components/paneSwap.contract.test.ts

@@ -11,6 +11,22 @@ const componentsDir = here;
  * Pane-swap contract — the enforcement half of the family's transition
  * primitives (user audit 2026-10-23).
  *
+ * THE DECISION TABLE (which surface for which class of slot):
+ *
+ *   ┌──────────────────────────────┬───────────────────────────────┐
+ *   │ the content can UNMOUNT      │ HkTransitionContainer (frame │
+ *   │ when it leaves the stage     │ must morph) / HkCrossfade    │
+ *   │                              │ (same-box dissolve)          │
+ *   ├──────────────────────────────┼───────────────────────────────┤
+ *   │ the instance must SURVIVE    │ HkPaneHolder (draft stores,  │
+ *   │ (draft store, canvas, sock)  │ canvases, sockets)           │
+ *   ├──────────────────────────────┼───────────────────────────────┤
+ *   │ a WIZARD STEPPER inside a    │ HkStepFlow — see its exception│
+ *   │ modal sheet                  │ below; it is a sibling with a │
+ *   │                              │ different contract, not a    │
+ *   │                              │ rogue pane slot              │
+ *   └──────────────────────────────┴───────────────────────────────┘
+ *
  * THE RULE. A "pane slot" is a container whose visible content is selected
  * by a state key while the container stays put: tabs, settings sections,
  * step bodies, view areas. Every such slot must swap through the standard
@@ -113,7 +129,34 @@ describe("pane-swap contract", () => {
       // wrapped by the standard above or justified here.
       "HkTabs.tsx", // wrapped by HkTransitionContainer (pinned above)
       "HkSettingsDialog.tsx", // wrapped by HkTransitionContainer (pinned above)
-      "HkStepFlow.tsx", // justified: frozen-sheet two-window protocol + direction axis
+      // HkStepFlow is NOT a rogue pane slot — it is a sibling mechanism
+      // with a contract the generic primitives deliberately do not
+      // offer (2026-10-24 deep-dive ruling; do not re-litigate without
+      // reading this):
+      //  1. SEQUENTIAL two-window choreography (slide with the hosting
+      //     sheet's height FROZEN, then the morph plays ALONE) — the
+      //     inversion of HkTransitionContainer's concurrent morph, born
+      //     from the 2026-09-23 round-16 user directive after the
+      //     concurrent form overloaded phone GPU raster threads
+      //     (whole-region black flashes no layering fix absorbed).
+      //  2. A direction axis (translateX travel + RTL mirroring) that
+      //     HkCrossfade's contract forbids — its tests pin
+      //     opacity-only, no transform, ever.
+      //  3. The hk-stepflow-swap sheet protocol: HkModal freezes its
+      //     height pin on "swap", safety-unfreezes (ms+650), and
+      //     height-morphs alone on "morph".
+      //  4. Six round-numbered field incidents live in its logic:
+      //     r16 align-self:start (grid stretch zeroed every shrink's
+      //     delta), r17 near-instant clip sweep (moving clip edges
+      //     re-raster per frame), r18 announce-AFTER-patch (a shrink
+      //     read the leaving body's geometry and no-opped), r22
+      //     Android-autofill strobe (dropFlowFocus before the swap),
+      //     r24 sticky-pin vs modal gutter-cover layering, and
+      //     preemptSwap keeping whichever body is actually visible
+      //     (opacity > 0.05) when interrupted mid-slide.
+      // Merging any of this into the generic container would change its
+      // semantics for every existing call site. Permanent exception.
+      "HkStepFlow.tsx",
       "HkAdminShell.tsx", // content slot is host-owned; hosts key it (chest wraps HkCrossfade)
       "HkThemePanelContent.tsx", // forwards to HTabs (HkTabs), inherits the mechanism
       "HkMenuPanel.tsx", // menu items, not a pane swap

package/src/components/windowControlsEdgeInset.contract.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Static pins for the window-controls chrome-edge contract (field report
+ * 2026-10-25: the chest login strip rendered the standard HkWindowControls
+ * cluster glued to the frame corner — zero right padding — while the chat
+ * face had ruled the inset to 12px/8px and the console face kept a full
+ * 24px of dead air; three faces, three ad-hoc computations of the same
+ * number). happy-dom has no layout engine, so — adminHeaderChrome-style —
+ * these read the declarations themselves; reverting any pinned value keeps
+ * the rest of the suite green, so each pin below is the only red-if-broken
+ * evidence for its contract. A deliberate rewrite is expected to update
+ * them.
+ *
+ * Pinned here:
+ *   1. the canonical tokens exist at :root (admin-tokens.scss top level —
+ *      a nested declaration would not reach host headers);
+ *   2. .s-glass-header--chrome sources BOTH bands from the tokens (the
+ *      in-library implementation of the host contract);
+ *   3. HkAdminHeader actually hangs the class from the `chrome` prop
+ *      (the prop without the class, or vice versa, ships the 24px inset);
+ *   4. the standard-mode HOST CONTRACT is documented on HkWindowControls
+ *      (the doc is the contract's prose home — keep it in sync).
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const adminTokens = readFileSync(join(here, "..", "styles", "admin-tokens.scss"), "utf8");
+const adminHeader = readFileSync(join(here, "HkAdminHeader.tsx"), "utf8");
+const windowControls = readFileSync(join(here, "HkWindowControls.tsx"), "utf8");
+
+/** Brace depth of `code` at character index `at` (0 = top level). */
+function braceDepthAt(code: string, at: number): number {
+  let depth = 0;
+  for (let i = 0; i < at; i += 1) {
+    if (code[i] === "{") depth += 1;
+    else if (code[i] === "}") depth -= 1;
+  }
+  return depth;
+}
+
+/** Declarations of every rule whose prelude IS `selector` (whole-prelude
+ *  match, comments stripped), with whether it sits inside an at-block. */
+function allRuleDeclarations(
+  source: string,
+  selector: string,
+): Array<{ nested: boolean; decls: Array<[string, string]> }> {
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, "");
+  const out: Array<{ nested: boolean; decls: Array<[string, string]> }> = [];
+  for (let at = code.indexOf(selector); at >= 0; at = code.indexOf(selector, at + 1)) {
+    const open = code.indexOf("{", at + selector.length);
+    if (open < 0) continue;
+    if (code.slice(at + selector.length, open).trim() !== "") continue;
+    let boundary = at - 1;
+    while (boundary >= 0 && !"}{;".includes(code[boundary])) boundary -= 1;
+    if (code.slice(boundary + 1, at).replace(/\s+/g, " ").trim() !== "") continue;
+    const nested = braceDepthAt(code, at) > 0;
+    const body = code.slice(open + 1, code.indexOf("}", open));
+    const decls: Array<[string, string]> = [];
+    for (const part of body.split(";")) {
+      const m = /^\s*([-a-zA-Z]+)\s*:\s*([\s\S]+?)\s*$/.exec(part);
+      if (m) decls.push([m[1], m[2].replace(/\s+/g, " ")]);
+    }
+    out.push({ nested, decls });
+  }
+  return out;
+}
+
+describe("window-controls chrome-edge contract (the three faces had drifted)", () => {
+  it("declares the canonical edge-inset tokens at :root top level", () => {
+    // :root is a top-level rule; a token declared inside an at-block (or
+    // renamed) silently falls every consumer back to its var() fallback —
+    // the token must exist AND sit where it cascades.
+    const rootRules = allRuleDeclarations(adminTokens, ":root").filter((r) => !r.nested);
+    expect(rootRules.length, ":root must be declared at top level").toBeGreaterThan(0);
+    const joined = rootRules.flatMap((r) => r.decls);
+    expect(joined).toContainEqual(["--hk-window-controls-edge-inset", "0.75rem"]);
+    expect(joined).toContainEqual(["--hk-window-controls-edge-inset-compact", "0.5rem"]);
+  });
+
+  it("sources the chrome header's desktop inset from the token (logical property)", () => {
+    // padding-INLINE-END, not padding-right: in a dir="rtl" host the
+    // caption row flips to the visual left and the inset must flip with
+    // it (same reasoning as the RTL-mirrored titlebar close button).
+    const rules = allRuleDeclarations(adminTokens, ".s-glass-header.s-glass-header--chrome").filter(
+      (r) => !r.nested,
+    );
+    expect(rules.length, ".s-glass-header--chrome must be declared at top level").toBe(1);
+    expect(rules[0].decls).toContainEqual([
+      "padding-inline-end",
+      "var(--hk-window-controls-edge-inset, 0.75rem)",
+    ]);
+  });
+
+  it("sources the chrome header's ≤1023px inset from the compact token", () => {
+    const rules = allRuleDeclarations(adminTokens, ".s-glass-header.s-glass-header--chrome").filter(
+      (r) => r.nested,
+    );
+    expect(rules.length, "the compact band must override the chrome inset").toBe(1);
+    expect(rules[0].decls).toContainEqual([
+      "padding-inline-end",
+      "var(--hk-window-controls-edge-inset-compact, 0.5rem)",
+    ]);
+  });
+
+  it("hangs the chrome class from the HkAdminHeader chrome prop", () => {
+    // The prop without the class (or the class without a producer) leaves
+    // the console face on the base 24px inset — both halves are the pin.
+    expect(adminHeader).toMatch(/chrome:\s*\{\s*type:\s*Boolean,\s*default:\s*false\s*\}/);
+    expect(adminHeader).toMatch(
+      /props\.chrome\s*\?\s*"s-glass-header--chrome"\s*:\s*""/,
+    );
+  });
+
+  it("documents the standard-mode host contract on HkWindowControls", () => {
+    // The doc comment is the contract's prose home: the token name and the
+    // never-flush rule must stay stated where hosts read the component.
+    expect(windowControls).toContain("HOST CONTRACT");
+    expect(windowControls).toContain("--hk-window-controls-edge-inset");
+    expect(windowControls).toContain("never rides the window edge");
+  });
+});

package/src/styles/admin-tokens.scss

@@ -9,6 +9,19 @@
   /* ── Layout tokens ─ */
   --s-footer-height: 3rem;
   --s-header-height: 3rem;
+
+  /* ── Window-control chrome insets ─
+   * The right padding a host title-bar header keeps between the standard
+   * HkWindowControls cluster and the window edge (canonical home since
+   * the chest login strip shipped the cluster glued to the frame corner —
+   * field report 2026-10-25). The standard cluster NEVER rides the edge
+   * (that is the flush variant's job), so every chrome face sources its
+   * padding from here instead of restating half-of-the-header-inset per
+   * face — the faces had drifted three ways (chat 12px/8px, console a
+   * full 24px of dead air, auth 0px). Values are the 2026-10-23 ruling's
+   * halvings of the base/compact header insets, promoted to tokens. */
+  --hk-window-controls-edge-inset: 0.75rem; /* desktop: half of the 24px base header inset */
+  --hk-window-controls-edge-inset-compact: 0.5rem; /* ≤1023px: half of the 16px compact header inset */
   /* Layout/type/motion scale tokens (--space-*, --text-*, --blur-*, --z-*,
    * --duration-*, --ease-*) used to be mirrored here ("keep both in sync")
    * — they now live once in styles/theme/scale.scss, which every entry
@@ -437,6 +450,27 @@
   padding: 0 var(--space-16);
 }
 
+/* Chrome variant (HkAdminHeader `chrome` prop — the desktop face whose
+ * header IS the window title bar): the inline-end inset follows the
+ * window-controls contract token, not the content inset — the default
+ * 24px reads as dead air next to the standard HkWindowControls cluster
+ * (the same 2026-10-23 user direction that halved the chat face's gap).
+ * LOGICAL property, like the RTL-mirrored titlebar close button (the
+ * [dir="rtl"] .hk-titlebar-btn-close rule in components/HkTitleBar.scss):
+ * in a dir="rtl" host the caption row flips to the visual left and the
+ * inset must flip with it, not stay on the physical right. (0,2,0)
+ * outranks the base rule and the compact band alike, so the chrome
+ * inset wins regardless of load order. */
+.s-glass-header.s-glass-header--chrome {
+  padding-inline-end: var(--hk-window-controls-edge-inset, 0.75rem);
+}
+
+@media (max-width: 1023px) {
+  .s-glass-header.s-glass-header--chrome {
+    padding-inline-end: var(--hk-window-controls-edge-inset-compact, 0.5rem);
+  }
+}
+
 /* ── Balanced header columns (the ONE three-zone header layout) ─────────
  * The shared geometry behind every top bar that owns a header-centre
  * group: the frontend chat header (chest ChatLayout's .s-header-bar-*)