@celestia-island/hikari 0.55.268 → 0.55.270

package/package.json

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

package/src/components/HkAboutModal.scss

@@ -262,16 +262,19 @@
 // across both palettes and modes) rather than shipping an unreadable tone
 // colour. The border and background keep the raw channel: only the glyphs owe
 // contrast, the tint is decorative.
+// NOTE (grass constraint, see scripts/sync-vue-mirror.py): the relative-colour
+// form oklch(from ... min/max(l,...) c h) was replaced by an oklab mix toward
+// black/white - an APPROXIMATION of the lightness cap/floor, not channel math.
 .s-about-modal-row-meta[data-tone="positive"] {
   border-color: rgb(var(--color-success) / 32%);
   background: rgb(var(--color-success) / 10%);
-  color: oklch(from rgb(var(--color-success)) min(l, 0.5) c h);
+  color: color-mix(in oklab, rgb(var(--color-success)) 60%, black);
 }
 
 .s-about-modal-row-meta[data-tone="caution"] {
   border-color: rgb(var(--color-warning) / 32%);
   background: rgb(var(--color-warning) / 10%);
-  color: oklch(from rgb(var(--color-warning)) min(l, 0.5) c h);
+  color: color-mix(in oklab, rgb(var(--color-warning)) 60%, black);
 }
 
 // Red state: the component is not wired up / unreachable. The row then
@@ -279,21 +282,21 @@
 .s-about-modal-row-meta[data-tone="danger"] {
   border-color: rgb(var(--color-error) / 32%);
   background: rgb(var(--color-error) / 10%);
-  color: oklch(from rgb(var(--color-error)) min(l, 0.5) c h);
+  color: color-mix(in oklab, rgb(var(--color-error)) 60%, black);
 }
 
 // Dark arm: floor the lightness instead of capping it (rationale above). Only
 // the glyphs re-ink — the border and tint already ride the live channel.
 [data-mode="dark"] .s-about-modal-row-meta[data-tone="positive"] {
-  color: oklch(from rgb(var(--color-success)) max(l, 0.72) c h);
+  color: color-mix(in oklab, rgb(var(--color-success)) 30%, white);
 }
 
 [data-mode="dark"] .s-about-modal-row-meta[data-tone="caution"] {
-  color: oklch(from rgb(var(--color-warning)) max(l, 0.72) c h);
+  color: color-mix(in oklab, rgb(var(--color-warning)) 30%, white);
 }
 
 [data-mode="dark"] .s-about-modal-row-meta[data-tone="danger"] {
-  color: oklch(from rgb(var(--color-error)) max(l, 0.72) c h);
+  color: color-mix(in oklab, rgb(var(--color-error)) 30%, white);
 }
 
 /* ── Links: licenses, external links, credits names and filings ───────── */

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

@@ -251,6 +251,14 @@ describe("HkAboutModal stylesheet contract", () => {
     const TONE = (tone: string) => `.s-about-modal-row-meta[data-tone=${tone}]`;
     const DARK_TONE = (tone: string) => `[data-mode=dark] ${TONE(tone)}`;
 
+    // GRASS CONSTRAINT (2026-11): the Rust mirror compiles these sheets
+    // through `grass`, which cannot parse relative colour syntax — so the
+    // seed-relative `oklch(from … min/max(l, …) c h)` arms this contract used
+    // to pin are now an oklab MIX toward black/white (an approximation of the
+    // lightness cap/floor, not channel math). See HkAboutModal.scss's NOTE and
+    // scripts/sync-vue-mirror.py; the approximation is tuned to the same
+    // contrast bound.
+    //
     // Channel behind each coloured tone, and the WCAG-AA ink derived from it.
     // The pill text is `--text-2xs` (10px) — small text, 4.5:1 — and the raw
     // channel misses that on both shipped palettes (stock light warning sits
@@ -268,9 +276,9 @@ describe("HkAboutModal stylesheet contract", () => {
     // (shipped once — chest #2027). Reverting an arm to the raw channel, or
     // dropping either mode arm, must turn this red.
     const AA_INK_LIGHT = (channel: string) =>
-      `oklch(from rgb(var(--color-${channel})) min(l, 0.5) c h)`;
+      `color-mix(in oklab, rgb(var(--color-${channel})) 60%, black)`;
     const AA_INK_DARK = (channel: string) =>
-      `oklch(from rgb(var(--color-${channel})) max(l, 0.72) c h)`;
+      `color-mix(in oklab, rgb(var(--color-${channel})) 30%, white)`;
     const TONES: Record<string, string> = {
       positive: "success",
       caution: "warning",

package/src/components/HkAltSignIn.tsx

@@ -17,7 +17,7 @@ export interface HkAltSignInEntry {
  *
  * A small muted trigger row (styled in the `.s-auth-footer` grammar) that
  * opens a popover listing third-party/alternative credential entries —
- * platform passkey on shittim-chest, feishu OAuth on easy-hydro-erp — so
+ * platform passkey on shittim-chest, feishu OAuth on the ERP adopter — so
  * both apps share one implementation and only differ in content.
  *
  * Entries render as [`HkMenuActionItem`] rows inside an [`HkPopover`]

package/src/components/HkAuthMethodList.test.tsx

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick } from "vue";
 
 import HkAuthMethodList from "./HkAuthMethodList";
@@ -15,6 +15,7 @@ function mount(node: ReturnType<typeof h>) {
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
@@ -61,17 +62,19 @@ describe("HkAuthMethodList", () => {
   });
 
   it("wraps every tile in a tooltip carrying the provider label", async () => {
+    vi.useFakeTimers();
     const c = mount(
       h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })),
     );
     const wrappers = c.querySelectorAll(".hk-tooltip-wrapper");
     expect(wrappers.length).toBe(2);
-    // Popups mount lazily on first engage — a touch tap mounts each one
-    // immediately — and then carry the label text.
+    // Popups mount lazily on first engage — hover each tile through the
+    // 300ms show delay (a touch press no longer mounts the popup: the
+    // touch half is the long-press hint bar, never the anchored popup).
     for (const w of wrappers) {
-      w.dispatchEvent(new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }));
+      w.dispatchEvent(new MouseEvent("mouseenter"));
     }
-    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(300);
     const popups = [...document.querySelectorAll(".hk-tooltip-popup .hk-tooltip-content")]
       .map((el) => el.textContent);
     expect(popups).toContain("GitHub");

package/src/components/HkBoard.tsx

@@ -2,7 +2,7 @@
  * HkBoard — the shared node-and-edge board surface.
  *
  * ONE world-camera canvas that every graph-like page builds on (history
- * topic maps, SCADA scenes, PLC panels, and whatever comes next). The
+ * topic maps, operations scenes, PLC panels, and whatever comes next). The
  * board owns the motion feel and the chrome; the page owns the layout:
  *
  *  - CAMERA: 5% geometric zoom ladder with an ANIMATED settle (no snapping),
@@ -221,7 +221,7 @@ export default defineComponent({
     let pinchBase: { cam: BoardCamera; dist: number; mid: BoardPoint } | null = null;
     let dragState: { node: BoardNodeInput; sx: number; sy: number; ox: number; oy: number; moved: boolean } | null = null;
     // Every node press is tracked (draggable or not) so read-only boards
-    // — SCADA scenes, mind maps — still get `nodeClick` on a short tap.
+    // — operations scenes, mind maps — still get `nodeClick` on a short tap.
     let pressed: { id: string; pointerId: number; x: number; y: number } | null = null;
 
     /** How many of the board's own pixels one DRAWN pixel is worth: the

package/src/components/HkColorSchemeDialog.test.ts

@@ -52,8 +52,8 @@ const SECTIONED_GROUP: TokenGroupDefinition = {
       label: { en: "Process media", "zh-Hans": "工艺介质" },
       slots: [
         {
-          key: "h2",
-          label: { en: "Hydrogen", "zh-Hans": "氢气" },
+          key: "buffer",
+          label: { en: "Buffer", "zh-Hans": "缓冲" },
           defaults: { dark: { r: 20, g: 184, b: 166 }, light: { r: 15, g: 118, b: 110 } },
         },
       ],
@@ -151,7 +151,7 @@ describe("HkColorSchemeDialog extension groups", () => {
     );
     expect(labels).toContain("L1 相（黄）");
     expect(labels).toContain("L2 相（绿）");
-    expect(labels).toContain("氢气");
+    expect(labels).toContain("缓冲");
 
     await setLocale("en");
   });

package/src/components/HkColorSchemeEditor.test.ts

@@ -50,8 +50,8 @@ const SECTIONED_GROUP: TokenGroupDefinition = {
       label: { en: "Process media", "zh-Hans": "工艺介质" },
       slots: [
         {
-          key: "h2",
-          label: { en: "Hydrogen", "zh-Hans": "氢气" },
+          key: "buffer",
+          label: { en: "Buffer", "zh-Hans": "缓冲" },
           defaults: { dark: { r: 20, g: 184, b: 166 }, light: { r: 15, g: 118, b: 110 } },
         },
       ],

package/src/components/HkCopyBadge.test.tsx

@@ -21,6 +21,7 @@ function mount(renderNode: () => ReturnType<typeof h>) {
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
@@ -128,33 +129,36 @@ describe("HkCopyBadge", () => {
     expect(writeText).not.toHaveBeenCalled();
   });
 
-  /** Engage the lazy tooltip without hovering: a touch tap mounts the
-   *  popup immediately (showNow), no fake timers needed. */
-  function engageTooltip(c: HTMLElement) {
-    c.querySelector(".hk-tooltip-wrapper")!.dispatchEvent(
-      new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }),
-    );
+  /** Engage the lazy tooltip the way a mouse user does: hover the
+   *  wrapper through the 300ms show delay. (A touch press no longer
+   *  mounts the popup — the touch half is the long-press hint bar, so
+   *  the tap vehicle this helper replaced is gone for good.) */
+  async function engageTooltip(c: HTMLElement) {
+    c.querySelector(".hk-tooltip-wrapper")!.dispatchEvent(new MouseEvent("mouseenter"));
+    await vi.advanceTimersByTimeAsync(300);
+    await nextTick();
   }
 
   it("renders the custom tooltip text", async () => {
+    vi.useFakeTimers();
     const c = mount(() => h(HkCopyBadge, { tooltip: "Open details" }, () => "#d.132"));
     // The popup mounts lazily on first engage (dense-list contract).
     expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     const content = document.body.querySelector(".hk-tooltip-popup .hk-tooltip-content");
     expect(content?.textContent).toBe("Open details");
   });
 
   it("shows the localized click-to-copy tooltip by default", async () => {
+    vi.useFakeTimers();
     const c = mount(() => h(HkCopyBadge, null, () => "#d.132"));
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     const content = document.body.querySelector(".hk-tooltip-popup .hk-tooltip-content");
     expect(content?.textContent).toBe("Click to copy");
   });
 
   it("links the badge to the popup via aria-describedby across the whole lifecycle", async () => {
+    vi.useFakeTimers();
     const c = mount(() => h(HkCopyBadge, { tooltip: "Open details" }, () => "#d.132"));
     const badge = c.querySelector(".hk-badge")!;
 
@@ -163,8 +167,7 @@ describe("HkCopyBadge", () => {
     expect(document.body.querySelector(".hk-tooltip-popup")).toBeNull();
 
     // Engage: describedby == the popup id.
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     const popup = document.body.querySelector(".hk-tooltip-popup")!;
     expect(badge.getAttribute("aria-describedby")).toBe(popup.getAttribute("id"));
     expect(popup.querySelector(".hk-tooltip-content")!.textContent).toBe("Open details");
@@ -175,8 +178,7 @@ describe("HkCopyBadge", () => {
     expect(badge.getAttribute("aria-describedby")).toBeNull();
 
     // Re-engage: returns, reusing the same popup element.
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     expect(badge.getAttribute("aria-describedby")).toBe(
       document.body.querySelector(".hk-tooltip-popup")!.getAttribute("id"),
     );

package/src/components/HkDraggableGrid.scss

@@ -16,7 +16,7 @@
   min-height: 44px;
   border: 1px dashed var(--hi-color-primary, #7aa2f7);
   border-radius: var(--radius-sm, 4px);
-  background: rgb(from var(--hi-color-primary, #7aa2f7) r g b / 0.04);
+  background: color-mix(in srgb, var(--hi-color-primary, #7aa2f7) 4%, transparent);
 }
 
 .hk-draggable-grid-cell {
@@ -47,7 +47,7 @@
     transform: scale(0.96);
     border-style: dashed;
     border-color: var(--hi-color-primary, #7aa2f7);
-    background: rgb(from var(--hi-color-primary, #7aa2f7) r g b / 0.04);
+    background: color-mix(in srgb, var(--hi-color-primary, #7aa2f7) 4%, transparent);
     cursor: grabbing;
   }
 

package/src/components/HkDraggableList.scss

@@ -31,7 +31,7 @@
     transform: scale(0.96);
     border-style: dashed;
     border-color: var(--hi-color-primary, #7aa2f7);
-    background: rgb(from var(--hi-color-primary, #7aa2f7) r g b / 0.04);
+    background: color-mix(in srgb, var(--hi-color-primary, #7aa2f7) 4%, transparent);
     cursor: grabbing;
   }
 

package/src/components/HkInput.password.test.tsx

@@ -34,7 +34,8 @@ const fakeCreateImageData = fakeFn<CanvasRenderingContext2D["createImageData"]>(
  *   click-to-toggle with auto-hide (revealAutoHideMs)
  * - the strength dot classifies through the shared passwordLevel util
  *   unless strengthEvaluator overrides it, and carries a localized
- *   tooltip that opens on hover AND on touch tap
+ *   tooltip that opens on hover (desktop) / via the touch long-press
+ *   hint bar (the touch half is the top bar, never the anchored popup)
  * - the native input stays type="password" at all times — the reveal
  *   pass draws on the canvas, so the value is never DOM text
  */
@@ -108,10 +109,14 @@ function fireBeforeinput(input: HTMLInputElement, inputType: string) {
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
   }
+  // The touch hint bar is presenter-owned module state (runtime/
+  // touchHint.ts) — tear the node out so a case remounts it fresh.
+  document.querySelectorAll(".hk-touch-hint-bar").forEach((el) => el.remove());
 });
 
 describe("HkInput password surface identity", () => {
@@ -566,32 +571,42 @@ describe("HkInput password strength traffic light", () => {
     ).toBe(false);
   });
 
-  it("opens the tooltip immediately on a touch tap and closes on an outside tap", async () => {
+  it("hints the strength on touch through the long-press bar, never the anchored popup", async () => {
+    vi.useFakeTimers();
     const { container } = mountPasswordInput("Password1", {
       passwordTrailing: "strength",
     });
     const wrapper = container.querySelector<HTMLElement>(".hk-tooltip-wrapper")!;
 
+    // A quick tap shows NOTHING: neither the anchored popup (hover/focus
+    // only) nor the top hint bar (the hold never elapsed).
     wrapper.dispatchEvent(
-      new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }),
+      new PointerEvent("pointerdown", { pointerType: "touch", pointerId: 1, bubbles: true }),
     );
-    await nextTick();
-
-    let popup = document.querySelector<HTMLElement>(".hk-tooltip-popup");
-    expect(popup?.classList.contains("hk-tooltip-visible")).toBe(true);
-    expect(popup?.textContent).toContain("Fair");
-
-    // Tap somewhere else: the capture-phase document listener hides it.
-    const outside = document.createElement("div");
-    document.body.appendChild(outside);
-    outside.dispatchEvent(
-      new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }),
+    await vi.advanceTimersByTimeAsync(100);
+    document.dispatchEvent(
+      new PointerEvent("pointerup", { pointerType: "touch", pointerId: 1, bubbles: true }),
     );
-    await nextTick();
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    expect(document.querySelector(".hk-touch-hint-bar")).toBeNull();
 
-    popup = document.querySelector<HTMLElement>(".hk-tooltip-popup");
-    expect(popup?.classList.contains("hk-tooltip-visible")).toBe(false);
-    outside.remove();
+    // The long-press fires the top-docked bar with the strength text…
+    wrapper.dispatchEvent(
+      new PointerEvent("pointerdown", { pointerType: "touch", pointerId: 1, bubbles: true }),
+    );
+    await vi.advanceTimersByTimeAsync(450);
+    const bar = document.querySelector<HTMLElement>(".hk-touch-hint-bar");
+    expect(bar?.classList.contains("is-on")).toBe(true);
+    expect(bar?.textContent).toContain("Fair");
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+
+    // …the lift starts the linger window, and the bar retires after it.
+    document.dispatchEvent(
+      new PointerEvent("pointerup", { pointerType: "touch", pointerId: 1, bubbles: true }),
+    );
+    await vi.advanceTimersByTimeAsync(2200);
+    expect(bar?.classList.contains("is-on")).toBe(false);
   });
 });
 

package/src/components/HkInput.scss

@@ -256,9 +256,11 @@
 }
 
 /* Autofill overrides */
+/* The finite duration (instead of `calc(infinity * 1s)`) keeps this sheet
+   compilable by the grass compiler the Rust form shares it with. */
 .hk-input-box input,
 .hk-input-box textarea {
-  transition: color calc(infinity * 1s) step-end, background-color calc(infinity * 1s) step-end;
+  transition: color 100000000s step-end, background-color 100000000s step-end;
 }
 
 .hk-input-box input:-webkit-autofill,

package/src/components/HkListTransition.scss

@@ -140,7 +140,11 @@
 .hk-list-reveal-enter-from,
 .hk-list-reveal-leave-to {
   opacity: 0;
-  height: calc-size(auto, size * 0.8);
+  /* grass-compatible fallback: the Rust form compiles this same sheet, and
+   * grass cannot parse `calc-size(auto, size * 0.8)` (see the sync script's
+   * compile constraints). 80% of the container is the closest equivalent the
+   * parser accepts; the enter/leave reveal keeps its opacity fade either way. */
+  height: 80%;
 }
 
 .hk-list-reveal-move {

package/src/components/HkMasonry.scss

@@ -0,0 +1,53 @@
+// AI-generated: developed with a DeepSeek Harness agent (model GLM-5.3-flash); human-directed.
+
+/* HkMasonry — the column geometry (see the component docblock for the
+ * contract). Independent flex columns, NOT CSS columns: a card is placed
+ * whole into one column, so nothing can fragment it and no balancer can
+ * go stale under it.
+ *
+ * Column spacing rides SIBLING MARGINS, never a container `gap` — the
+ * same lesson HkWaterfall's sheet records: a gap is spent between every
+ * adjacent pair of rendered flex items, including a (live, collapsed)
+ * pair, so a trailing empty column would shave the survivor narrower than
+ * the host's other full-width children. A sibling margin is only spent
+ * where two width-carrying columns actually sit, and an empty column
+ * cancels it on both edges.
+ *
+ * Hosts tune the density with --hk-masonry-gap (vertical card gap inside a
+ * column AND the horizontal sibling margin); it defaults to --space-12. */
+
+.hk-masonry {
+  display: flex;
+  align-items: flex-start;
+}
+
+.hk-masonry-col {
+  flex: 1 1 0;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--hk-masonry-gap, var(--space-12));
+}
+
+.hk-masonry-col + .hk-masonry-col {
+  margin-inline-start: var(--hk-masonry-gap, var(--space-12));
+}
+
+/* Fewer cards than columns: the empty column must not keep its flex share
+   (the survivor would render half width beside a ghost), and with the
+   sibling-margin spacing above its collapse costs no gap on either edge. */
+.hk-masonry-col[data-empty] {
+  flex: 0 0 0;
+  margin-inline-start: 0;
+}
+
+.hk-masonry-col[data-empty] + .hk-masonry-col {
+  margin-inline-start: 0;
+}
+
+/* The card wrapper is layout-transparent: the slot content owns its own
+   chrome, and the wrapper exists so the observer measures ONE stable box
+   per key regardless of what the card renders. */
+.hk-masonry-card {
+  min-width: 0;
+}

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

@@ -0,0 +1,109 @@
+// AI-generated: developed with a DeepSeek Harness agent (model GLM-5.3-flash); human-directed.
+
+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 guard for HkMasonry's column geometry — the axis a
+ * runtime suite cannot see (happy-dom applies no stylesheets).
+ *
+ * The invariant this pins: columns are independent flex stacks whose
+ * spacing is SIBLING MARGIN, cancelled on a collapsed ([data-empty])
+ * column on both edges — never a container `gap` (a gap is spent on the
+ * (live, collapsed) pair too and shaves the survivor narrower than the
+ * host's other full-width children), and NEVER a CSS-multicol property
+ * (`columns` / `break-inside`), the fragmentation layout this component
+ * exists to replace. Same ownership discipline as the HkWaterfall sheet
+ * guard: the compiled sheet must contain EXACTLY the rules below, each
+ * with EXACTLY its pinned declaration list, and nothing else in the sheet
+ * may mention the columns.
+ *
+ * Vitest stubs CSS, so the runtime suite can never catch a lost rule —
+ * this compiles the sheet directly and asserts the contract.
+ */
+
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+const compiled = compile(resolve(componentDir, "HkMasonry.scss"), {
+  style: "expanded",
+}).css;
+
+// Expanded sass keeps comments inline and may emit an @charset preamble;
+// both must go before rule parsing or they glue onto captured selectors.
+const css = compiled
+  .replace(/\/\*[\s\S]*?\*\//g, "")
+  .replace(/^@charset[^;]*;/m, "");
+
+function rules(source: string): { selector: string; decls: string[] }[] {
+  expect(source, "no at-rule may appear in the compiled sheet").not.toContain(
+    "@",
+  );
+  expect(source, "no nested braces in the compiled sheet").not.toMatch(
+    /\{[^{}]*\{/,
+  );
+  return [...source.matchAll(/([^{}]+)\{([^{}]*)\}/g)].map((m) => ({
+    selector: m[1].replace(/\s+/g, " ").trim(),
+    decls: m[2]
+      .split(";")
+      .map((d) => d.replace(/\s+/g, " ").trim())
+      .filter(Boolean),
+  }));
+}
+
+const allRules = (): { selector: string; decls: string[] }[] => rules(css);
+
+function expectRule(selector: string, decls: string[]): void {
+  const hits = allRules().filter((r) => r.selector === selector);
+  expect(hits, `exactly one "${selector}" rule`).toHaveLength(1);
+  expect(hits[0].decls, `declarations of "${selector}"`).toEqual(decls);
+}
+
+function columnRules(): { selector: string; decls: string[] }[] {
+  return allRules().filter((r) => r.selector.includes("hk-masonry-col"));
+}
+
+describe("HkMasonry column spacing contract", () => {
+  it("compiles into the expected flat sheet", () => {
+    expect(css).toContain(".hk-masonry");
+  });
+
+  it("the column machinery is exactly five rules with exactly these declarations", () => {
+    expect(columnRules().map((r) => r.selector).sort()).toEqual(
+      [
+        ".hk-masonry-col",
+        ".hk-masonry-col + .hk-masonry-col",
+        ".hk-masonry-col[data-empty]",
+        ".hk-masonry-col[data-empty] + .hk-masonry-col",
+      ].sort(),
+    );
+    expectRule(".hk-masonry-col", [
+      "flex: 1 1 0",
+      "min-width: 0",
+      "display: flex",
+      "flex-direction: column",
+      "gap: var(--hk-masonry-gap, var(--space-12))",
+    ]);
+    expectRule(".hk-masonry-col + .hk-masonry-col", [
+      "margin-inline-start: var(--hk-masonry-gap, var(--space-12))",
+    ]);
+    expectRule(".hk-masonry-col[data-empty]", [
+      "flex: 0 0 0",
+      "margin-inline-start: 0",
+    ]);
+    expectRule(".hk-masonry-col[data-empty] + .hk-masonry-col", [
+      "margin-inline-start: 0",
+    ]);
+  });
+
+  it("the sheet never speaks fragmentation layout", () => {
+    // The whole point of the component: no multicol anywhere, in any rule,
+    // under any alias the shorthand family offers.
+    expect(css).not.toMatch(/\bcolumns\s*:/);
+    expect(css).not.toMatch(/break-inside/);
+    expect(css).not.toMatch(/column-(gap|count|fill|width)/);
+  });
+});