@celestia-island/hikari 0.55.134 → 0.55.136

package/package.json

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

package/src/components/HkDraggableList.scss

@@ -71,6 +71,18 @@
   }
 }
 
+/* A list where every row is locked can never reorder, so the handle lane
+ * has nothing to offer — collapse it instead of reserving an empty gutter
+ * that reads as "missing grips" (user report 2026-10-11: chest's 2FA
+ * factors list). Mixed lists are unaffected: they keep the lane on every
+ * row (locked ones render it hidden via [data-hidden]) so the grip column
+ * stays aligned. */
+.hk-draggable-list[data-all-locked] {
+  .hk-draggable-list-handle {
+    display: none;
+  }
+}
+
 .hk-draggable-list-content {
   flex: 1;
   min-width: 0;

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

@@ -0,0 +1,64 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Sheet contract for the locked-row handle lane (DOM twin:
+ * HkDraggableList.test.tsx).
+ *
+ * - a locked row HIDES its grip but keeps the 20px lane reserved
+ *   (`visibility: hidden` under [data-hidden]) — mixed lists keep the
+ *   grip column aligned;
+ * - a list whose every row is locked (root [data-all-locked]) can never
+ *   reorder, so the lane collapses outright (`display: none`) instead of
+ *   reserving an empty gutter that reads as "missing grips" (user report
+ *   2026-10-11 on chest's 2FA factors list).
+ *
+ * Assertions run on the COMPILED sheet, not the source text, so a
+ * declaration cannot hide behind SCSS nesting, and comments are stripped
+ * first so a commented-out guard cannot keep a hollow test green.
+ */
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+function listCss(): string {
+  const file = resolve(componentDir, "HkDraggableList.scss");
+  return compile(file, { style: "expanded", loadPaths: [componentDir] }).css.replace(
+    /\/\*[\s\S]*?\*\//g,
+    "",
+  );
+}
+
+function ruleBody(css: string, selector: string): string | null {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const m = css.match(new RegExp(`${escaped}\\s*\\{([^}]*)\\}`));
+  return m ? m[1]! : null;
+}
+
+describe("HkDraggableList handle-lane sheet", () => {
+  const css = listCss();
+
+  it("compiles", () => {
+    expect(css.length).toBeGreaterThan(0);
+    // Sanity anchors so a renamed file cannot hollow this guard.
+    expect(css).toContain(".hk-draggable-list-item");
+    expect(css).toContain(".hk-draggable-list-handle");
+  });
+
+  it("keeps a locked row's lane reserved — hidden, not removed", () => {
+    const body = ruleBody(css, ".hk-draggable-list-handle[data-hidden]");
+    expect(body, "the [data-hidden] rule must exist").not.toBeNull();
+    expect(body).toContain("visibility: hidden");
+    expect(body).not.toContain("display: none");
+  });
+
+  it("collapses the lane entirely when every row is locked", () => {
+    const body = ruleBody(
+      css,
+      ".hk-draggable-list[data-all-locked] .hk-draggable-list-handle",
+    );
+    expect(body, "the [data-all-locked] collapse rule must exist").not.toBeNull();
+    expect(body).toContain("display: none");
+  });
+});

package/src/components/HkDraggableList.test.tsx

@@ -0,0 +1,182 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+
+import HDraggableList from "./HkDraggableList";
+
+/**
+ * DOM contract for the locked-row handle lane.
+ *
+ * Every row renders a 20px handle lane so the grip column stays aligned
+ * across draggable and locked rows; a locked row hides its grip
+ * (`data-hidden` → visibility: hidden — reserved, not removed). When
+ * EVERY row is locked the list can never reorder at all, and an
+ * all-hidden lane reads as "missing grips" rather than "locked" (user
+ * report 2026-10-11 on chest's 2FA factors list): the root then carries
+ * `data-all-locked` and the sheet collapses the lane entirely (the sheet
+ * twin of this contract: HkDraggableList.styles.test.ts). A custom
+ * `handle` slot rides the same lane, so it collapses with it.
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  while (mounts.length) {
+    const { app, container } = mounts.pop()!;
+    app.unmount();
+    container.remove();
+  }
+});
+
+function mountList(items: string[], lockedKeys: string[]): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(
+        HDraggableList,
+        { items: items.map((key) => ({ key })), lockedKeys },
+        {
+          item: ({ item }: { item: { key: string } }) =>
+            h("span", { class: "row-body" }, item.key),
+        },
+      ),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container.querySelector(".hk-draggable-list") as HTMLElement;
+}
+
+function handlesOf(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll(".hk-draggable-list-handle"));
+}
+
+describe("HkDraggableList locked-lane contract", () => {
+  it("hides a locked row's grip but keeps the lane in mixed lists", () => {
+    const root = mountList(["a", "b"], ["b"]);
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+    const handles = handlesOf(root);
+    expect(handles).toHaveLength(2);
+    expect(handles[0]!.hasAttribute("data-hidden")).toBe(false);
+    expect(handles[1]!.hasAttribute("data-hidden")).toBe(true);
+  });
+
+  it("marks an all-locked list so the sheet can collapse the lane", () => {
+    const root = mountList(["a", "b"], ["a", "b"]);
+
+    expect(root.hasAttribute("data-all-locked")).toBe(true);
+    // Handles stay in the DOM (consumers count them — chest's 2FA
+    // contract test does); the collapse is presentational, carried by
+    // the sheet, so the marker is the load-bearing part here.
+    const handles = handlesOf(root);
+    expect(handles).toHaveLength(2);
+    expect(handles.every((handle) => handle.hasAttribute("data-hidden"))).toBe(true);
+  });
+
+  it("flips the marker reactively as the last draggable row locks", async () => {
+    const lockedKeys = ref<string[]>([]);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }, { key: "b" }], lockedKeys: lockedKeys.value },
+          {
+            item: ({ item }: { item: { key: string } }) =>
+              h("span", { class: "row-body" }, item.key),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const root = container.querySelector(".hk-draggable-list") as HTMLElement;
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+
+    lockedKeys.value = ["a", "b"];
+    await nextTick();
+
+    expect(root.hasAttribute("data-all-locked")).toBe(true);
+  });
+
+  it("collapses a custom handle slot with the lane in an all-locked list", () => {
+    // The handle slot renders INSIDE the lane span, so the collapse rule
+    // hides custom grips the same as the default six-dot svg.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: [{ key: "a" }], lockedKeys: ["a"] },
+          {
+            item: ({ item }: { item: { key: string } }) =>
+              h("span", { class: "row-body" }, item.key),
+            handle: () => h("span", { class: "custom-grip" }, "≡"),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+
+    const grip = container.querySelector(".custom-grip") as HTMLElement;
+    expect(grip).not.toBeNull();
+    // The custom grip rides the lane span that the sheet display:nones.
+    expect(grip.closest(".hk-draggable-list-handle")).not.toBeNull();
+    expect(grip.closest(".hk-draggable-list")).not.toBeNull();
+    expect(
+      (grip.closest(".hk-draggable-list") as HTMLElement).hasAttribute("data-all-locked"),
+    ).toBe(true);
+  });
+
+  it("carries no marker on an empty list", () => {
+    const root = mountList([], []);
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+    expect(handlesOf(root)).toHaveLength(0);
+  });
+
+  it("ignores locked keys that match no row — membership, not counts", () => {
+    // Guards against a length-arithmetic refactor
+    // (lockedKeys.length >= items.length): TWO phantom keys vs two rows
+    // satisfy the count yet lock nothing — the list stays draggable and
+    // the lane must stay.
+    const phantomOnly = mountList(["a", "b"], ["zzz", "yyy"]);
+    expect(phantomOnly.hasAttribute("data-all-locked")).toBe(false);
+
+    // A superset still marks: every real row IS locked.
+    const superset = mountList(["a", "b"], ["zzz", "a", "b"]);
+    expect(superset.hasAttribute("data-all-locked")).toBe(true);
+  });
+
+  it("flips the marker reactively as rows are added around a locked one", async () => {
+    const items = ref<{ key: string }[]>([{ key: "a" }]);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HDraggableList,
+          { items: items.value, lockedKeys: ["a"] },
+          {
+            item: ({ item }: { item: { key: string } }) =>
+              h("span", { class: "row-body" }, item.key),
+          },
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const root = container.querySelector(".hk-draggable-list") as HTMLElement;
+
+    expect(root.hasAttribute("data-all-locked")).toBe(true);
+
+    items.value = [{ key: "a" }, { key: "b" }];
+    await nextTick();
+
+    expect(root.hasAttribute("data-all-locked")).toBe(false);
+  });
+});

package/src/components/HkDraggableList.tsx

@@ -22,6 +22,10 @@ export default defineComponent({
   name: "HkDraggableList",
   props: {
     items: { type: Array as PropType<DragListItem[]>, required: true },
+    /** Row keys that may not be dragged. A locked row hides its grip but
+     *  keeps the handle lane reserved ([data-hidden]); when EVERY row is
+     *  locked the root carries data-all-locked and the sheet collapses
+     *  the lane entirely — the list cannot reorder at all. */
     lockedKeys: { type: Array as PropType<string[]>, default: () => [] },
   },
   emits: {
@@ -198,8 +202,19 @@ export default defineComponent({
     return () => {
       void tick.value;
       const s = drag.value;
+      // A list whose every row is locked can never reorder (chest's 2FA
+      // factor list is the all-locked case), and an all-hidden lane reads
+      // as "missing grips" rather than "locked" (user report 2026-10-11).
+      // Mark the root so the sheet can collapse the lane outright; mixed
+      // lists keep it on every row for grip-column alignment.
+      const allLocked =
+        props.items.length > 0 && props.items.every((item) => isLocked(item.key));
       return (
-        <div class="hk-draggable-list" data-dragging={s ? "" : undefined}>
+        <div
+          class="hk-draggable-list"
+          data-dragging={s ? "" : undefined}
+          data-all-locked={allLocked || undefined}
+        >
           {props.items.map((item, index) => {
             const locked = isLocked(item.key);
             const isSource = s != null && s.fromIndex === index;

package/src/components/HkMenu.tsx

@@ -157,6 +157,17 @@ export default defineComponent({
      * length, applied on the `dvh`-capable branch, never sanitized.
      */
     maxHeight: { type: String, default: undefined },
+    /**
+     * Forwarded to the desktop popout panels' `autoFlip` (HkSelectPanel):
+     * whether a panel whose placed side cannot host it migrates to the
+     * opposite vertical side. Default true — every existing consumer
+     * keeps the flip. Hosts that must keep the popup on its placed side
+     * (the fill-template field's vocabulary panel anchors DIRECTLY BELOW
+     * its field, user direction 2026-10-10) pass `false`; the viewport
+     * clamp then absorbs the overflow instead. Mobile sheets have no
+     * flip to make — the prop never reaches them.
+     */
+    autoFlip: { type: Boolean, default: true },
     /**
      * Sidebar variant only: every collapsible group renders EXPANDED
      * until the user collapses it — nav sidebars that read as a table of
@@ -606,6 +617,7 @@ export default defineComponent({
           offset={cfg.offset}
           matchAnchorWidth={cfg.match}
           maxHeight={props.maxHeight}
+          autoFlip={props.autoFlip}
           onUpdate:open={(v: boolean) => {
             if (!v) onRootCloseRequest();
           }}
@@ -634,6 +646,7 @@ export default defineComponent({
               placement="bottom-start"
               offset={0}
               maxHeight={props.maxHeight}
+              autoFlip={props.autoFlip}
               onUpdate:open={(v: boolean) => {
                 if (!v) onSubCloseRequest(level);
               }}

package/src/components/HkSelectPanel.test.tsx

@@ -431,6 +431,38 @@ describe("HkSelectPanel custom invocation", () => {
       window.innerHeight = prevHeight;
     }
   });
+
+  it("autoFlip: false keeps a starved bottom popout below its anchor (clamped)", async () => {
+    // The below-first rule (HkTemplateField's vocabulary panel): an
+    // anchor near the viewport bottom with room only ABOVE must not
+    // migrate the panel above — with autoFlip off the placed side holds
+    // (data-side stays "bottom", so the pop motion still grows the panel
+    // out of the anchor's bottom edge) and the clamp slides the panel up
+    // only as far as full visibility requires. The default flips the
+    // same rig top-side — that direction is pinned by the tall-popout
+    // clamp test above.
+    const prevHeight = window.innerHeight;
+    window.innerHeight = 800;
+    try {
+      const { container, open } = mountPanel({ placement: "bottom-start", autoFlip: false });
+      await nextTick();
+
+      const anchor = container.querySelector<HTMLButtonElement>("button")!;
+      anchor.getBoundingClientRect = () =>
+        ({ top: 760, bottom: 780, left: 40, right: 140, width: 100, height: 20 }) as DOMRect;
+      open.value = true;
+      await nextTick();
+
+      const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+      expect(host.dataset.side).toBe("bottom");
+      // Raw top 780 + offset 4 = 784 overflows on an 800px viewport
+      // (happy-dom measures the panel at the 200px fallback): the clamp
+      // pins it to 800 - 200 - 16 = 584 instead of flipping.
+      expect(Number.parseInt(host.style.top, 10)).toBe(584);
+    } finally {
+      window.innerHeight = prevHeight;
+    }
+  });
 });
 
 describe("HkSelectPanel back-guard (window-first back priority)", () => {

package/src/components/HkSelectPanel.tsx

@@ -91,6 +91,19 @@ export default defineComponent({
       type: String as PropType<SelectPanelPlacement>,
       default: "bottom-start",
     },
+    /**
+     * Auto-flip to the opposite vertical side when the placed side cannot
+     * host the panel. Default true — plain dropdowns read better flipped
+     * than clamped over their trigger. Surfaces whose popup must stay
+     * anchored BELOW their field regardless of how the viewport happens
+     * to be filled (the fill-template field's vocabulary panel: user
+     * direction 2026-10-10 — it opens in the flow under the input, never
+     * migrating above it) pass `false`: the panel keeps the placed side
+     * and the viewport clamp absorbs the overflow instead (an oversized
+     * panel slides up over the anchor only as far as full visibility
+     * requires).
+     */
+    autoFlip: { type: Boolean, default: true },
     /** Gap between anchor and popout, in px. */
     offset: { type: Number, default: 4 },
     /** Popout min-width follows the anchor width (select parity). */
@@ -557,13 +570,17 @@ export default defineComponent({
         side === "top"
           ? r.top - props.offset - ph
           : r.bottom + props.offset;
-      // Auto-flip when the chosen side cannot host the panel.
-      if (side === "bottom" && top + ph > frame.y + frame.height - pad) {
-        side = "top";
-        top = r.top - props.offset - ph;
-      } else if (side === "top" && top < frame.y + pad) {
-        side = "bottom";
-        top = r.bottom + props.offset;
+      // Auto-flip when the chosen side cannot host the panel (opt-out
+      // via autoFlip: false keeps the placed side; the clamp below then
+      // absorbs an overflow instead of migrating the panel).
+      if (props.autoFlip) {
+        if (side === "bottom" && top + ph > frame.y + frame.height - pad) {
+          side = "top";
+          top = r.top - props.offset - ph;
+        } else if (side === "top" && top < frame.y + pad) {
+          side = "bottom";
+          top = r.bottom + props.offset;
+        }
       }
       const align = props.placement.endsWith("-center")
         ? "center"

package/src/components/HkTemplateField.scss

@@ -75,7 +75,19 @@
   min-height: calc(1.5rem + var(--space-4, 4px));
   display: flex;
   flex-wrap: wrap;
-  align-items: center;
+  // Baseline alignment (user direction 2026-10-10): the chip's smaller
+  // monospace text must share the literal text's BASELINE, not its box
+  // midpoint — `center` centered the chip's box, which floats the chip's
+  // baseline a fraction above the surrounding text's (smaller font,
+  // same-height line) and read as the chip riding high. Baseline is the
+  // flex-native fix: text runs and chips (inline-flex, whose baseline
+  // is its content text's) align on one shared baseline with no pixel
+  // nudges. `align-content: center` keeps the single-line read
+  // vertically centered inside the min-height box — the line sizes to
+  // its content and the LINE centers, where plain `baseline` alone
+  // would top-align it in the stretched line.
+  align-items: baseline;
+  align-content: center;
   gap: 2px 3px;
   font-size: var(--text-base, 0.875rem);
   line-height: 1.5;

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

@@ -17,7 +17,12 @@ import { describe, expect, it } from "vitest";
  *      mobile sheet must keep the panel as the ONE scroll region;
  *   2. the scroll host is a positioning context (`position: relative`)
  *      for the overlay rails;
- *   3. a curated class list checks TSX→CSS (no unstyled element) and a
+ *   3. the edit's children align on the shared text BASELINE
+ *      (`align-items: baseline` + `align-content: center`) and no chip
+ *      rule carries a manual vertical nudge — the flex alignment IS the
+ *      fix for the chip-rides-high report, a pixel hack would be a
+ *      regression;
+ *   4. a curated class list checks TSX→CSS (no unstyled element) and a
  *      reverse scan flags any `hk-tpl-*`/`hk-template-*` selector in the
  *      sheet that no source file renders (no dead rule).
  */
@@ -109,6 +114,41 @@ describe("HkTemplateField stylesheet contract", () => {
     expect(css).toMatch(/\.hk-tpl-editor-scroll\s*\{[^}]*position:\s*relative/s);
   });
 
+  it("aligns the edit's children on the shared text baseline, never box centers", () => {
+    // The chip's smaller monospace text must share the literal text's
+    // BASELINE (flex-native `align-items: baseline`), not the box
+    // midpoint — centering the box floats the chip's baseline a fraction
+    // above the surrounding text's and reads as the chip riding high
+    // (user report 2026-10-10). Restoring `center` must fail here.
+    expect(css).toMatch(/\.hk-template-field-edit\s*\{[^}]*align-items:\s*baseline/s);
+    expect(css).not.toMatch(/\.hk-template-field-edit\s*\{[^}]*align-items:\s*center/s);
+    // The single-line read stays vertically centered in the min-height
+    // box via the LINE centering (align-content) — plain baseline alone
+    // would top-align it in the stretched line.
+    expect(css).toMatch(/\.hk-template-field-edit\s*\{[^}]*align-content:\s*center/s);
+    // The chip editor's current-token line (static chip + description)
+    // has been baseline-aligned since introduction — it predates the
+    // edit-container fix and stays that way (an R1 review round caught
+    // a mutation-recovery slip that had silently flipped it).
+    expect(css).toMatch(/\.hk-tpl-editor-current\s*\{[^}]*align-items:\s*baseline/s);
+  });
+
+  it("aligns chips by flex baseline, never by pixel nudges", () => {
+    // The baseline contract is the alignment layout itself: no manual
+    // vertical offsets on the chip inside the edit (a margin/translate
+    // hack would re-introduce the drift the alignment fixes, tuned to
+    // one font size). The dark-mode and unknown variants ride the same
+    // box, so the whole chip block must stay offset-free.
+    const chipRules = [...css.matchAll(/([^{}]*\.hk-tpl-chip[^{}]*)\{([^}]*)\}/g)];
+    // Extraction sanity (never trust a 0-hit scan): the chip is styled.
+    expect(chipRules.length).toBeGreaterThan(0);
+    for (const [, selector, body] of chipRules) {
+      expect(body, `chip rule ${(selector ?? "").trim()} must not nudge vertically`).not.toMatch(
+        /margin-(top|bottom)|translate[XY]|\btop:|\bbottom:|vertical-align/,
+      );
+    }
+  });
+
   it("styles every editor class the TSX renders", () => {
     const emitted = classTokensFrom(tsx);
     for (const cls of ["hk-template-field", "hk-template-field-edit", "hk-template-field-box",

package/src/components/HkTemplateField.test.tsx

@@ -774,3 +774,85 @@ describe("HkTemplateField vocabulary semantics guards", () => {
     expect(active[0]!.textContent).toContain("username");
   });
 });
+
+describe("HkTemplateField popup direction (below-first)", () => {
+  /** Fixed visual rect (the rootzoom rig's shape). */
+  function rect(x: number, y: number, w: number, h: number): DOMRect {
+    return {
+      x, y, width: w, height: h, top: y, left: x, right: x + w, bottom: y + h,
+      toJSON: () => ({}),
+    } as DOMRect;
+  }
+
+  async function flushFrames() {
+    await nextTick();
+    for (let i = 0; i < 3; i++) {
+      await new Promise((r) => setTimeout(r, 0));
+      await new Promise((r) => requestAnimationFrame(() => r(null)));
+    }
+  }
+
+  it("the vocabulary panel stays below a field anchored near the viewport bottom", async () => {
+    // Below-first (user direction 2026-10-10): a low field with room only
+    // ABOVE must not migrate the panel above the field — the panel keeps
+    // the placed bottom side (data-side drives the pop motion's origin)
+    // and the viewport clamp absorbs the overflow. The default-flip
+    // behavior for plain panels is pinned over in HkSelectPanel's own
+    // suite; this pins the field's opt-out through the HkMenu wiring.
+    const prevHeight = window.innerHeight;
+    window.innerHeight = 800;
+    try {
+      const el = mount({ modelValue: "" });
+      await nextTick();
+      const edit = editable(el);
+      edit.getBoundingClientRect = () => rect(40, 760, 300, 20);
+      await openTrigger(el, "{{ us");
+
+      const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+      expect(host).toBeTruthy();
+      expect(host.dataset.side).toBe("bottom");
+      // Raw top 780 + menu offset 6 = 786 overflows the 800px viewport
+      // (the panel measures at the 200px happy-dom fallback): clamped to
+      // 800 - 200 - 16 = 584 instead of flipping.
+      expect(Number.parseInt(host.style.top, 10)).toBe(584);
+    } finally {
+      window.innerHeight = prevHeight;
+    }
+  });
+
+  it("the chip editor popover stays below a chip anchored near the viewport bottom", async () => {
+    // Same below-first rule for the chip editor (autoFlip off on the
+    // HPopover): without it, a 300px-tall panel beside a chip with 20px
+    // of room below flips top-side — exactly the overlap the user
+    // reported. The panel's rect is faked at the prototype (the
+    // rootzoom rig's approach) so the flip comparison has real numbers.
+    const prevHeight = window.innerHeight;
+    window.innerHeight = 800;
+    const gBCR = vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(
+      function (this: HTMLElement) {
+        if (this.classList.contains("hk-tpl-chip")) return rect(40, 760, 120, 20);
+        if (this.classList.contains("hk-popover-panel")) return rect(0, 0, 220, 300);
+        return rect(0, 0, 0, 0);
+      },
+    );
+    try {
+      const el = mount({ modelValue: "https://g.com/{{username}}.png" });
+      await nextTick();
+      editable(el).querySelector<HTMLElement>(".hk-tpl-chip")!.click();
+      await flushFrames();
+
+      const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+      expect(panel).toBeTruthy();
+      // No flip: the resolved placement keeps the bottom side.
+      expect(panel.className).toContain("hk-popover-bottom-start");
+      expect(panel.className).not.toContain("hk-popover-top-start");
+      // And the position: raw top 780 + offset 4 = 784, clamped to
+      // 800 - 300 - 16 = 484 (full visibility beats the anchor gap).
+      const host = panel.parentElement!;
+      expect(host.style.top).toBe("484px");
+    } finally {
+      gBCR.mockRestore();
+      window.innerHeight = prevHeight;
+    }
+  });
+});

package/src/components/HkTemplateField.tsx

@@ -59,12 +59,14 @@ function isSubsequence(query: string, text: string): boolean {
  * the styled form of the exact template it serializes to — Gutenberg
  * style, without any block chrome:
  *
- * - typing `{{` opens the vocabulary panel (desktop: anchored under the
- *   caret's field; phone: the standard bottom sheet) and picking a row
- *   inserts the chip; typing a full `{{ name }}` by hand converts it
- *   just the same;
- * - clicking a chip opens the chip editor (desktop: a popover beside
- *   the chip; phone: a bottom sheet) whose form owns the concrete
+ * - typing `{{` opens the vocabulary panel (desktop: anchored DIRECTLY
+ *   BELOW the field — below-first by user direction 2026-10-10, the
+ *   viewport clamp absorbs a short viewport instead of a flip; phone:
+ *   the standard bottom sheet) and picking a row inserts the chip;
+ *   typing a full `{{ name }}` by hand converts it just the same;
+ * - clicking a chip opens the chip editor (desktop: a popover directly
+ *   below the chip, same below-first rule; phone: a bottom sheet) whose
+ *   form owns the concrete
  *   editing — swap the placeholder for another vocabulary entry, read
  *   what it fills from, or remove it — and FOCUS MOVES INTO the form so
  *   the next keystroke lands there;
@@ -1015,9 +1017,13 @@ export const HkTemplateField = defineComponent({
         {props.hint && !props.error && <p class="hk-template-field-hint">{props.hint}</p>}
         {props.error && <p class="hk-template-field-error">{props.error}</p>}
 
-        {/* Vocabulary panel — anchored under the field on desktop, the
-            standard bottom sheet on phone. The editable keeps focus;
-            rows click through, arrows/Enter ride the editable keydown. */}
+        {/* Vocabulary panel — anchored DIRECTLY BELOW the field on
+            desktop (autoFlip off, user direction 2026-10-10: the panel
+            opens in the flow under the input it completes; when the
+            viewport below is too short the clamp slides it up only as
+            far as full visibility requires), the standard bottom sheet
+            on phone. The editable keeps focus; rows click through,
+            arrows/Enter ride the editable keydown. */}
         <HkMenu
           variant="popup"
           items={[]}
@@ -1029,6 +1035,7 @@ export const HkTemplateField = defineComponent({
           placement="bottom-start"
           matchAnchorWidth
           maxHeight="min(18rem, 45dvh)"
+          autoFlip={false}
           title={t("hikari::templateField.suggestTitle", "Placeholders")}
         >
           {filteredTokens.value.length > 0 ? (
@@ -1053,8 +1060,10 @@ export const HkTemplateField = defineComponent({
           )}
         </HkMenu>
 
-        {/* Chip editor — a popover beside the chip on desktop, a bottom
-            sheet on phone; the form inside owns the concrete editing. */}
+        {/* Chip editor — a popover directly below the chip on desktop
+            (autoFlip off, same below-first rule as the vocabulary panel:
+            user direction 2026-10-10), a bottom sheet on phone; the form
+            inside owns the concrete editing. */}
         <HPopover
           modelValue={editorOpen.value}
           onUpdate:modelValue={(v: boolean) => {
@@ -1073,6 +1082,7 @@ export const HkTemplateField = defineComponent({
           anchorRef={editorChip.value}
           sheetOnMobile
           placement="bottom-start"
+          autoFlip={false}
           title={t("hikari::templateField.chipEditorTitle", "Edit placeholder")}
         >
           <div class="hk-tpl-editor" onFocusin={() => { editorHoldsFocus.value = true; }}>