@celestia-island/hikari 0.55.26 → 0.55.28

package/package.json

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

package/src/components/HkDockBar.scss

@@ -14,8 +14,10 @@
   align-items: center;
   gap: var(--space-4, 4px);
 
-  /* ── page anchor: absolute bottom-center of the nearest positioned
-   *     ancestor, resting --hk-dock-inset above its content floor. */
+  /* ── page anchor (SOUTH edge): absolute bottom-center of the nearest
+   *     positioned ancestor, resting --hk-dock-inset above its content
+   *     floor. `bottom` below is the compass spelling of the same
+   *     geometry. */
   &[data-anchor="page"] {
     position: absolute;
     left: 50%;
@@ -31,6 +33,42 @@
     margin: 0 auto var(--hk-dock-inset, 12px);
   }
 
+  /* ── horizontal edge anchors: north and the compass spelling of the
+   *     south edge — absolute, centered along the edge. */
+  &[data-anchor="top"],
+  &[data-anchor="bottom"] {
+    position: absolute;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 50;
+  }
+
+  &[data-anchor="top"] {
+    top: var(--hk-dock-inset, 12px);
+  }
+
+  &[data-anchor="bottom"] {
+    bottom: var(--hk-dock-inset, 12px);
+  }
+
+  /* ── vertical edge anchors (west / east): the dock runs vertically,
+   *     centered on the edge midpoint. */
+  &[data-anchor="left"],
+  &[data-anchor="right"] {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    z-index: 50;
+  }
+
+  &[data-anchor="left"] {
+    left: var(--hk-dock-inset, 12px);
+  }
+
+  &[data-anchor="right"] {
+    right: var(--hk-dock-inset, 12px);
+  }
+
   /* ── corner anchors: absolute attachment with the same inset, for
    *     pagers, toolbars and HUD panels that live off-center. */
   &[data-anchor="top-left"],
@@ -73,6 +111,7 @@
   align-items: stretch;
   width: var(--dock-width, auto);
   max-width: var(--dock-max-width, calc(100vw - var(--space-16, 16px)));
+  max-height: var(--dock-max-height, none);
   padding: var(--dock-padding, var(--space-8, 8px) var(--space-12, 12px));
   background: rgb(var(--color-surface));
   border: 1px solid var(--border-subtle);
@@ -82,6 +121,14 @@
   box-shadow: var(--glow-dock);
 }
 
+/* Vertical side docks (west / east edges) stack along the viewport's
+ * tall axis — cap them viewport-aware by default so a tall dock never
+ * runs off-screen; --dock-max-height still overrides. */
+.hk-dock-bar[data-anchor="left"] .hk-dock-bar-surface,
+.hk-dock-bar[data-anchor="right"] .hk-dock-bar-surface {
+  max-height: var(--dock-max-height, calc(100dvh - var(--space-16, 16px)));
+}
+
 /* Glass surface (default) — blur the page canvas behind the dock. */
 .hk-dock-bar[data-surface="glass"] .hk-dock-bar-surface {
   backdrop-filter: blur(var(--blur-lg));

package/src/components/HkDockBar.test.tsx

@@ -1,4 +1,7 @@
 import { afterEach, describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createApp, defineComponent, h, nextTick } from "vue";
 
 import HkDockBar from "./HkDockBar";
@@ -49,23 +52,34 @@ describe("HkDockBar", () => {
     expect(root.dataset.surface).toBe("glass");
   });
 
-  it.each(["plane", "top-left", "top-right", "bottom-left", "bottom-right"] as const)(
-    "accepts the %s anchor",
-    async (anchor) => {
-      const root = await mountDock({ anchor });
-      expect(root.dataset.anchor).toBe(anchor);
-    },
-  );
+  it.each(
+    [
+      "plane",
+      "top",
+      "bottom",
+      "left",
+      "right",
+      "top-left",
+      "top-right",
+      "bottom-left",
+      "bottom-right",
+    ] as const,
+  )("accepts the %s anchor", async (anchor) => {
+    const root = await mountDock({ anchor });
+    expect(root.dataset.anchor).toBe(anchor);
+  });
 
-  it("exposes style hooks for width, max-width and padding", async () => {
+  it("exposes style hooks for width, max-width, max-height and padding", async () => {
     const root = await mountDock({
       width: "22rem",
       maxWidth: "30rem",
+      maxHeight: "60vh",
       padding: "4px 6px",
     });
     const style = root.style;
     expect(style.getPropertyValue("--dock-width")).toBe("22rem");
     expect(style.getPropertyValue("--dock-max-width")).toBe("30rem");
+    expect(style.getPropertyValue("--dock-max-height")).toBe("60vh");
     expect(style.getPropertyValue("--dock-padding")).toBe("4px 6px");
   });
 
@@ -74,3 +88,116 @@ describe("HkDockBar", () => {
     expect(root.dataset.surface).toBe("solid");
   });
 });
+
+// ── Anchor geometry contract ──────────────────────────────────────────────
+// SCSS source contract (house pattern, cf. HkButton icon-only contract):
+// happy-dom does not lay out, so each compass direction's geometry is
+// pinned textually against HkDockBar.scss. Dropping any one direction's
+// rule — or regressing its mapping (inset side / centering transform) —
+// turns the matching assertion red.
+
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkDockBar.scss"), "utf8");
+
+/** Every SCSS rule body whose selector list mentions the anchor. */
+function rulesFor(anchor: string): string {
+  const re = new RegExp(`&\\[data-anchor="${anchor}"\\][^{]*\\{[^}]*\\}`, "g");
+  return scss.match(re)?.join("\n") ?? "";
+}
+
+describe("HkDockBar anchor geometry contract", () => {
+  const INSET = "var(--hk-dock-inset, 12px)";
+
+  it.each(["page", "bottom"] as const)(
+    "%s docks to the south edge, centered (the two spellings share geometry)",
+    (anchor) => {
+      const rules = rulesFor(anchor);
+      expect(rules, `${anchor} rules must exist`).toBeTruthy();
+      expect(rules).toContain("position: absolute");
+      expect(rules).toContain("left: 50%");
+      expect(rules).toContain(`bottom: ${INSET}`);
+      expect(rules).toContain("transform: translateX(-50%)");
+    },
+  );
+
+  it("top docks to the north edge, centered", () => {
+    const rules = rulesFor("top");
+    expect(rules, "top rules must exist").toBeTruthy();
+    expect(rules).toContain("position: absolute");
+    expect(rules).toContain("top: " + INSET);
+    expect(rules).toContain("left: 50%");
+    expect(rules).toContain("transform: translateX(-50%)");
+    expect(rules).not.toContain(`bottom: ${INSET}`);
+  });
+
+  it.each(["left", "right"] as const)(
+    "%s docks to the vertical edge midpoint, centered by translateY",
+    (anchor) => {
+      const rules = rulesFor(anchor);
+      expect(rules, `${anchor} rules must exist`).toBeTruthy();
+      expect(rules).toContain("position: absolute");
+      expect(rules).toContain("top: 50%");
+      expect(rules).toContain(`${anchor}: ${INSET}`);
+      expect(rules).toContain("transform: translateY(-50%)");
+      // A side dock must not pick up the horizontal-edge centering.
+      expect(rules).not.toContain("transform: translateX(-50%)");
+    },
+  );
+
+  it.each(
+    [
+      ["top-left", "top", "left", "flex-start"],
+      ["top-right", "top", "right", "flex-end"],
+      ["bottom-left", "bottom", "left", "flex-start"],
+      ["bottom-right", "bottom", "right", "flex-end"],
+    ] as const,
+  )("%s docks into its corner with both insets", (anchor, side1, side2, align) => {
+    const rules = rulesFor(anchor);
+    expect(rules, `${anchor} rules must exist`).toBeTruthy();
+    expect(rules).toContain("position: absolute");
+    expect(rules).toContain(`${side1}: ${INSET}`);
+    expect(rules).toContain(`${side2}: ${INSET}`);
+    expect(rules).toContain(`align-items: ${align}`);
+  });
+
+  it("page and plane stay semantically distinct: page floats, plane flows", () => {
+    const page = rulesFor("page");
+    const plane = rulesFor("plane");
+    expect(page).toContain("position: absolute");
+    expect(plane, "plane rule must exist").toBeTruthy();
+    expect(plane).toContain("margin: 0 auto");
+    expect(plane).not.toContain("position: absolute");
+  });
+
+  it("consumes the size custom properties on every anchor via the base surface rule", () => {
+    // The anchor-agnostic base surface rule is the ONLY SCSS consumer of
+    // the size props for page/top/bottom/plane/corner docks — only the
+    // vertical side anchors get the viewport-aware cap override below.
+    // The style-hook tests above pin that the custom properties are set;
+    // this pins that the base rule still consumes them, so maxWidth /
+    // maxHeight cannot silently stop working off-side.
+    const base = scss.match(/\.hk-dock-bar-surface\s*\{[^}]*\}/)?.[0];
+    expect(base, "base surface rule must exist").toBeTruthy();
+    expect(base).toContain("width: var(--dock-width, auto)");
+    expect(base).toContain("max-width: var(--dock-max-width");
+    expect(base).toContain("max-height: var(--dock-max-height, none)");
+    expect(base).toContain("padding: var(--dock-padding");
+  });
+
+  it("caps vertical side docks viewport-aware by default", () => {
+    const sideCap = scss.match(
+      /\.hk-dock-bar\[data-anchor="left"\] \.hk-dock-bar-surface[^{]*\{[^}]*\}/,
+    )?.[0];
+    expect(sideCap, "side-anchor surface cap rule must exist").toBeTruthy();
+    expect(sideCap).toContain("max-height: var(--dock-max-height");
+    expect(sideCap).toContain("100dvh");
+  });
+
+  it("solid surface drops the backdrop blur in CSS, not just in data", () => {
+    const solid = scss.match(
+      /\.hk-dock-bar\[data-surface="solid"\] \.hk-dock-bar-surface\s*\{[^}]*\}/,
+    )?.[0];
+    expect(solid, "solid surface rule must exist").toBeTruthy();
+    expect(solid).toContain("backdrop-filter: none");
+  });
+});

package/src/components/HkDockBar.tsx

@@ -5,6 +5,10 @@ import "./HkDockBar.scss";
 export type HkDockBarAnchor =
   | "page"
   | "plane"
+  | "top"
+  | "bottom"
+  | "left"
+  | "right"
   | "top-left"
   | "top-right"
   | "bottom-left"
@@ -19,14 +23,30 @@ export type HkDockBarSurface = "glass" | "solid";
  * (surface, blur, border, radius, reverse glow) means no dock surface
  * ever re-declares its own background or shadow again.
  *
- * Anchors:
- *   - `page`  (default): absolute bottom-center of the nearest positioned
- *     ancestor, `--hk-dock-inset` above its content floor.
- *   - `plane`: in-flow — the host provides the plane (e.g. a fixed
- *     footer band); this container centers the surface horizontally.
+ * Anchors — the full eight-way compass (4 edges + 4 corners):
+ *   - `page` (default) and `bottom`: absolute bottom-center of the
+ *     nearest positioned ancestor (the SOUTH edge), `--hk-dock-inset`
+ *     above its content floor. `page` is the 2026-09-02 spelling kept
+ *     for existing callers; `bottom` is its compass alias — identical
+ *     geometry, pick either.
+ *   - `top`: absolute top-center (north edge) with the same inset.
+ *   - `left` / `right`: absolute middle of the west / east edge — the
+ *     dock runs vertically and is centered with translateY; its surface
+ *     gets a viewport-aware default max-height.
  *   - `top-left` / `top-right` / `bottom-left` / `bottom-right`:
  *     absolute corner attachment with the same inset, for pagers,
  *     toolbars and HUD panels that live off-center.
+ *   - `plane`: NOT a compass direction — in-flow; the host provides
+ *     the plane (e.g. a fixed footer band) and this container centers
+ *     the surface horizontally. Use it when the host owns positioning.
+ *
+ * Relationship to HkScrollContainer: that component's dockTop /
+ * dockBottom named slots are the contract for docks that live INSIDE a
+ * scrolling region — pinned to the scroll viewport, excluded from the
+ * scroll flow. HkDockBar is the carrier for docks that FLOAT over a
+ * canvas or page instead. Pick by host: scrolling region →
+ * HkScrollContainer dock slots; canvas/page overlay → HkDockBar. Do
+ * not nest an HkDockBar inside a scroll viewport expecting pinning.
  *
  * Surfaces:
  *   - `glass` (default): translucent surface + backdrop blur.
@@ -39,8 +59,9 @@ export type HkDockBarSurface = "glass" | "solid";
 const HkDockBar = defineComponent({
   name: "HkDockBar",
   props: {
-    /** Which plane carries the dock: page (bottom-center), a host plane
-     *  (in-flow), or one of the four corners. */
+    /** Which plane carries the dock: a compass anchor (4 edges + 4
+     *  corners, `page` being the south edge), or a host plane
+     *  (in-flow). */
     anchor: { type: String as PropType<HkDockBarAnchor>, default: "page" },
     /** Surface finish: glass (blur) or solid (moving canvas). */
     surface: { type: String as PropType<HkDockBarSurface>, default: "glass" },
@@ -48,6 +69,9 @@ const HkDockBar = defineComponent({
     width: { type: String, default: undefined },
     /** CSS max-width of the surface (content caps, e.g. minimap clearance). */
     maxWidth: { type: String, default: undefined },
+    /** CSS max-height of the surface; defaults to a viewport-aware cap
+     *  on the vertical side anchors (left / right), none elsewhere. */
+    maxHeight: { type: String, default: undefined },
     /** CSS padding override; defaults to the shared chrome rhythm. */
     padding: { type: String, default: undefined },
   },
@@ -56,6 +80,7 @@ const HkDockBar = defineComponent({
       const s: Record<string, string> = {};
       if (props.width) s["--dock-width"] = props.width;
       if (props.maxWidth) s["--dock-max-width"] = props.maxWidth;
+      if (props.maxHeight) s["--dock-max-height"] = props.maxHeight;
       if (props.padding) s["--dock-padding"] = props.padding;
       return s;
     });

package/src/components/HkSignInCard.test.ts

@@ -166,4 +166,57 @@ describe("HkSignInCard", () => {
     expect(c.querySelector(".s-auth-methods")).toBeTruthy();
     expect(c.querySelector(".methods-probe")).toBeTruthy();
   });
+
+  // ── Account-first mode (passwordField: false) ─────────────────────────
+
+  it("omits the password field entirely in account-first mode", () => {
+    const c = mount(h(HkSignInCard, { title: "T", passwordField: false }));
+    expect(usernameField(c)).toBeTruthy();
+    expect(passwordField(c)).toBeNull();
+    // No hidden input may survive either: a password-type field on a form
+    // that never carries a password would still trip credential-manager
+    // save prompts.
+    expect(c.querySelector('input[type="password"]')).toBeNull();
+  });
+
+  it("submits with an empty password once only the account name is typed", async () => {
+    const onSubmit = vi.fn();
+    const c = mount(h(HkSignInCard, { title: "T", passwordField: false, onSubmit }));
+    const btn = c.querySelector(".hk-btn-primary") as HTMLElement;
+    // Empty username still gates the submit.
+    expect(btn.getAttribute("disabled")).not.toBeNull();
+    typeInto(usernameField(c), "demiurge");
+    await Promise.resolve();
+    expect(btn.getAttribute("disabled")).toBeNull(); // no password expected
+    btn.click();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(onSubmit).toHaveBeenCalledWith("demiurge", "");
+  });
+
+  it("does not submit on Enter with an empty username in account-first mode", async () => {
+    const onSubmit = vi.fn();
+    const c = mount(h(HkSignInCard, { title: "T", passwordField: false, onSubmit }));
+    usernameField(c).dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Enter", bubbles: true }),
+    );
+    await Promise.resolve();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it("seeds the username field from initialUsername", () => {
+    const c = mount(
+      h(HkSignInCard, { title: "T", passwordField: false, initialUsername: "  demiurge " }),
+    );
+    expect((usernameField(c) as HTMLInputElement).value).toBe("  demiurge ");
+    // And the seeded name alone satisfies the submit guard.
+    const btn = c.querySelector(".hk-btn-primary") as HTMLElement;
+    expect(btn.getAttribute("disabled")).toBeNull();
+  });
+
+  it("keeps the password guard when passwordField is unset (default true)", () => {
+    const c = mount(h(HkSignInCard, { title: "T", initialUsername: "demiurge" }));
+    const btn = c.querySelector(".hk-btn-primary") as HTMLElement;
+    expect(btn.getAttribute("disabled")).not.toBeNull(); // password still empty
+  });
 });

package/src/components/HkSignInCard.tsx

@@ -28,6 +28,12 @@ import HkAuthSubmitButton from "./HkAuthSubmitButton";
  * - `usernamePlaceholder` / `usernameType` — override the username field
  *   (e.g. email-identifier logins); the placeholder falls back to the
  *   `hikari::signIn.usernamePlaceholder` locale when unset.
+ * - `passwordField: false` — account-first sign-in: the card collects ONLY
+ *   the account name and `submit` fires with an empty password. The
+ *   password itself is proven in the consumer's NEXT step (chest's
+ *   verify-account panel), where it reappears as one factor among several.
+ *   Pair with `initialUsername` so the typed name survives the step-flow
+ *   round-trip (the card remounts when the user navigates back).
  * - `footer` slot — content below the submit button (remember-me,
  *   protocol links, …).
  * - `methods` slot — forwarded to HkAuthCard's full-width methods block
@@ -67,21 +73,31 @@ export const HkSignInCard = defineComponent({
     usernameType: { type: String, default: "text" },
     /** Username placeholder; defaults to the hikari::signIn locale. */
     usernamePlaceholder: { type: String, default: undefined },
+    /** Account-first flows: hide the password field entirely — the card
+     *  collects only the account name and `submit` fires with an empty
+     *  password (the consumer's next step owns the actual proof). Default
+     *  keeps the classic two-field card. */
+    passwordField: { type: Boolean, default: true },
+    /** Seed for the username field. Step flows remount this card when the
+     *  user navigates back from a later step, so the typed account name
+     *  must travel through a prop rather than module state. */
+    initialUsername: { type: String, default: "" },
   },
   emits: {
-    /** Fired on explicit click or Enter; never with empty fields or while busy. */
+    /** Fired on explicit click or Enter; never with an empty username (or
+     *  an empty password while `passwordField` is on) or while busy. */
     submit: (_username: string, _password: string) => true,
   },
   setup(props, { emit, slots }) {
     const { t } = useI18n();
-    const username = ref("");
+    const username = ref(props.initialUsername);
     const password = ref("");
 
     function attemptSubmit() {
       if (props.loading || props.disabled) return;
       const u = username.value.trim();
-      if (!u || !password.value) return;
-      emit("submit", u, password.value);
+      if (!u || (props.passwordField && !password.value)) return;
+      emit("submit", u, props.passwordField ? password.value : "");
     }
 
     return () => (
@@ -132,21 +148,27 @@ export const HkSignInCard = defineComponent({
                     ),
                 }}
               </HkInput>
-              <HkInput
-                variant="password"
-                modelValue={password.value}
-                onUpdate:modelValue={(v: string) => (password.value = v)}
-                name="signin-password"
-                autocomplete={props.passwordAutocomplete ?? credentialAutocomplete("password", "current-password")}
-                placeholder={t("hikari::signIn.passwordPlaceholder", "Password")}
-                disabled={props.loading || props.disabled}
-                submitOnEnter={attemptSubmit}
-              />
+              {/* Account-first mode omits the field entirely — not hides
+                  it with CSS: a hidden password input would still plant a
+                  credential-manager save prompt and an autocomplete target
+                  on a form that never carries a password. */}
+              {props.passwordField && (
+                <HkInput
+                  variant="password"
+                  modelValue={password.value}
+                  onUpdate:modelValue={(v: string) => (password.value = v)}
+                  name="signin-password"
+                  autocomplete={props.passwordAutocomplete ?? credentialAutocomplete("password", "current-password")}
+                  placeholder={t("hikari::signIn.passwordPlaceholder", "Password")}
+                  disabled={props.loading || props.disabled}
+                  submitOnEnter={attemptSubmit}
+                />
+              )}
               <HkAuthSubmitButton
                 label={props.submitLabel ?? t("hikari::signIn.submit", "Sign in")}
                 block
                 loading={props.loading}
-                disabled={props.disabled || !username.value.trim() || !password.value}
+                disabled={props.disabled || !username.value.trim() || (props.passwordField && !password.value)}
                 doSubmit={() => Promise.resolve(attemptSubmit())}
               />
               </form>

package/src/theme/useTheme.test.ts

@@ -114,13 +114,15 @@ describe("useTheme lean cssvar injection", () => {
     });
   });
 
-  it("writes theme vars into a managed :root style block, never inline", () => {
+  it("writes theme vars into a managed html:root style block, never inline", () => {
     theme.initTheme();
     const styleEl = document.head.querySelector("style[data-hikari-theme-vars]");
     expect(styleEl).not.toBeNull();
     // Real browsers compute the static defaults, so the block holds only the
-    // true deltas; either way it is a :root block, not an inline attribute.
-    expect(styleEl!.textContent).toMatch(/^:root\{/);
+    // true deltas; either way it is an html:root block (specificity 0,1,1 —
+    // it must outrank every :root-level static seed regardless of document
+    // order), not an inline attribute.
+    expect(styleEl!.textContent).toMatch(/^html:root\{/);
     expect(styleEl!.textContent).toContain("--color-primary");
     // The html inline style attribute stays clean — no token vars on it.
     expect(document.documentElement.style.getPropertyValue("--color-primary")).toBe("");
@@ -133,9 +135,39 @@ describe("useTheme lean cssvar injection", () => {
     theme.useTheme().setTheme("nord");
     const blocks = document.head.querySelectorAll("style[data-hikari-theme-vars]");
     expect(blocks).toHaveLength(1);
-    expect(blocks[0].textContent).toMatch(/^:root\{/);
+    expect(blocks[0].textContent).toMatch(/^html:root\{/);
     expect(blocks[0].textContent).not.toBe(before);
   });
+
+  it("a :root seed injected AFTER the managed block cannot un-theme the page", () => {
+    // The 2026-09-18 dev.cw incident: every hikari component sheet @uses
+    // tokens.scss, so a lazily-loaded route chunk re-emits the static seed
+    // as a `:root` rule appended to <head> after this block — same
+    // specificity, later in the cascade, and the brand palette lost to it
+    // on the login page. The managed block therefore carries html:root
+    // (0,1,1), which outranks any :root-level emission (0,1,0) regardless
+    // of document order.
+    theme.initTheme();
+    const styleEl = document.head.querySelector("style[data-hikari-theme-vars]")!;
+    expect(styleEl.textContent).toContain("--color-primary");
+
+    const computed = () =>
+      getComputedStyle(document.documentElement).getPropertyValue("--color-primary").trim();
+    const themed = computed();
+    expect(themed).not.toBe("");
+
+    // Simulate the route-chunk seed: a :root rule with the static default,
+    // appended LAST (exactly what a lazy chunk's <link> does).
+    const seed = document.createElement("style");
+    seed.textContent = ":root{--color-primary:122 162 247;--color-background:214 236 240;--color-surface:240 244 248;}";
+    document.head.appendChild(seed);
+    expect(computed()).toBe(themed);
+
+    // Re-applying the theme must keep winning, too (no one-shot luck).
+    theme.useTheme().setTheme("nord");
+    expect(computed()).not.toBe("122 162 247");
+    seed.remove();
+  });
 });
 
 describe("useTheme preset/custom shadowing", () => {

package/src/theme/useTheme.ts

@@ -149,7 +149,7 @@ const THEME_TRANSITION_DURATION = 300;
 let transitionTimer: CronHandle | null = null;
 
 /**
- * Theme vars live in ONE managed stylesheet block (`:root` overrides)
+ * Theme vars live in ONE managed stylesheet block (`html:root` overrides)
  * instead of a hundred inline declarations on `<html style="...">`.
  *  - Inline style attributes bloat the DOM, show up as giant devtools
  *    noise on the root element, defeat caching of the token set and make
@@ -162,8 +162,20 @@ let transitionTimer: CronHandle | null = null;
  *    so a token whose value already resolves identically needs no
  *    override at all — a default-ish theme injects a handful of vars
  *    instead of ~80.
+ *
+ * The selector is `html:root`, not plain `:root`, on purpose: the static
+ * seed is `:root`-level, and lazy route chunks re-emit it (every component
+ * sheet `@use`s tokens.scss) into `<link>`s appended to `<head>` AFTER
+ * this block — a same-specificity `:root` there would silently beat the
+ * runtime palette and un-theme every late-loaded route (2026-09-18,
+ * dev.cw login: the HkOtpInput chunk flattened the brand palette back to
+ * the static seed). `html:root` (0,1,1) outranks every `:root`-level
+ * declaration (0,1,0) regardless of document order, while staying below
+ * inline styles and equal to `html[data-theme]` decor rules (order
+ * decides between those two, so a later decor can still override).
  */
 const THEME_VARS_STYLE_ATTR = "data-hikari-theme-vars";
+const THEME_VARS_SELECTOR = "html:root";
 
 function normalizeVarValue(value: string): string {
   return value.replace(/\s+/g, " ").trim();
@@ -214,7 +226,7 @@ function injectThemeVars(el: HTMLElement, vars: Record<string, string>): void {
 
   const deltas = pickThemeVarDeltas(vars, baseline);
   styleEl.textContent = Object.keys(deltas).length > 0
-    ? `:root{${Object.entries(deltas).map(([key, value]) => `${key}:${value}`).join(";")}}`
+    ? `${THEME_VARS_SELECTOR}{${Object.entries(deltas).map(([key, value]) => `${key}:${value}`).join(";")}}`
     : "";
 }