@celestia-island/hikari 0.55.194 → 0.55.196

package/package.json

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

package/src/components/HkAlert.scss

@@ -116,7 +116,7 @@
   transition: background var(--duration-fast, 0.15s) ease, color var(--duration-fast, 0.15s) ease;
 
   &:hover {
-    background: var(--hi-color-surface, #f0f4f8);
+    background: var(--hi-color-surface, #ffffff);
     color: var(--hi-color-text-primary, #1e1e1e);
   }
 

package/src/components/HkCheckbox.scss

@@ -33,7 +33,7 @@
    * --hi-color-border is the faint divider channel (15% alpha) and melts
    * into white/dark surfaces. */
   border: 1px solid rgb(var(--color-border, 100 100 100));
-  background: var(--hi-color-surface, rgba(240,244,248,0.95));
+  background: var(--hi-color-surface, rgba(255,255,255,0.95));
   transition:
     border-color var(--duration-normal, 0.3s) ease,
     background var(--duration-normal, 0.3s) ease,
@@ -95,7 +95,7 @@
    :focus-visible keeps mouse toggles ring-free. */
 .hk-checkbox-box:has(.hk-checkbox-input:focus-visible) {
   box-shadow:
-    0 0 0 2px var(--hi-color-surface, rgba(240,244,248,0.95)),
+    0 0 0 2px var(--hi-color-surface, rgba(255,255,255,0.95)),
     0 0 0 4px var(--hi-color-primary, #7aa2f7);
 }
 

package/src/components/HkDrawer.scss

@@ -26,7 +26,7 @@
   position: fixed;
   display: flex;
   flex-direction: column;
-  background: var(--hk-drawer-bg, var(--hi-color-surface, rgba(240,244,248,0.95)));
+  background: var(--hk-drawer-bg, var(--hi-color-surface, rgba(255,255,255,0.95)));
   // Token-gated (was a hard blur(12px)): the drawer resizes through
   // animated width/height, and a backdrop-filter on a resizing fixed
   // layer re-rasters the blurred region every frame — on phones that

package/src/components/HkEmptyState.scss

@@ -12,7 +12,7 @@
    panel — usually already provides a surface, and an always-on box turned
    every in-card empty state into a nested placeholder layer. */
 .hk-empty-state--boxed {
-  background: var(--hk-empty-bg, var(--hi-color-surface, rgba(240,244,248,0.95)));
+  background: var(--hk-empty-bg, var(--hi-color-surface, rgba(255,255,255,0.95)));
   backdrop-filter: blur(var(--blur-sm, 8px));
   border: 1px solid var(--hi-color-border, rgba(100,100,100,0.06));
   border-radius: var(--radius-md, 0.5rem);

package/src/components/HkFab.scss

@@ -85,12 +85,12 @@ $sizes: (sm: 34px, md: 42px, lg: 50px);
 
 .hk-fab[data-variant="glass"] .hk-fab-button {
   color: var(--hi-color-text-secondary, #666666);
-  background: color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 78%, transparent);
+  background: color-mix(in srgb, var(--hi-color-surface, #ffffff) 78%, transparent);
   border: 1px solid color-mix(in srgb, var(--hi-color-border, rgba(100,100,100,0.12)) 25%, transparent);
   backdrop-filter: blur(var(--blur-xs, 4px)); // chip language shared with autotag pills
   box-shadow: 0 4px 16px rgba(0, 0, 0, 0.14);
 
-  &:hover:not(:disabled) { background: color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 92%, transparent); }
+  &:hover:not(:disabled) { background: color-mix(in srgb, var(--hi-color-surface, #ffffff) 92%, transparent); }
 }
 
 .hk-fab[data-variant="primary"] .hk-fab-button {
@@ -130,7 +130,7 @@ $sizes: (sm: 34px, md: 42px, lg: 50px);
   letter-spacing: 0.02em;
   white-space: nowrap;
   color: var(--hi-color-text-secondary, #666666);
-  background: color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 82%, transparent);
+  background: color-mix(in srgb, var(--hi-color-surface, #ffffff) 82%, transparent);
   border: 1px solid color-mix(in srgb, var(--hi-color-border, rgba(100,100,100,0.12)) 25%, transparent);
   border-radius: var(--radius-full, 9999px);
   cursor: pointer;
@@ -149,7 +149,7 @@ $sizes: (sm: 34px, md: 42px, lg: 50px);
   &:focus-visible { outline: 2px solid var(--hi-color-primary, #7aa2f7); outline-offset: 1px; }
   &:disabled { opacity: 0.35; cursor: not-allowed; }
   // 82%→94% mirrors the main glass hover ladder (78%→92%).
-  &:hover:not(:disabled) { background: color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 94%, transparent); }
+  &:hover:not(:disabled) { background: color-mix(in srgb, var(--hi-color-surface, #ffffff) 94%, transparent); }
 }
 
 // Staggered reveal while expanded (CSS only, via nth-child delay).

package/src/components/HkIconButtonGroup.scss

@@ -22,7 +22,7 @@
   padding: var(--space-2, 0.125rem);
   border: 1px solid var(--border-faint);
   border-radius: var(--radius-md, 8px);
-  background: rgb(var(--color-surface, 240 244 248) / 60%);
+  background: rgb(var(--color-surface, 255 255 255) / 60%);
 }
 
 .hk-icon-group-sm {
@@ -196,7 +196,7 @@
 
 .hk-icon-group-item-marker-success {
   background: rgb(var(--color-success, 14 184 64));
-  box-shadow: 0 0 0 0.125rem rgb(var(--color-surface, 240 244 248));
+  box-shadow: 0 0 0 0.125rem rgb(var(--color-surface, 255 255 255));
 }
 
 /* Slider items already establish position:relative for the thumb stack —

package/src/components/HkKeywordSearchModal.scss

@@ -13,7 +13,7 @@
   align-items: center;
   gap: var(--space-8, 0.5rem);
   padding: var(--space-8, 0.5rem) var(--space-12, 0.75rem);
-  background: var(--hi-color-surface, rgba(240,244,248,0.95));
+  background: var(--hi-color-surface, rgba(255,255,255,0.95));
   border: 1px solid var(--hk-kw-border, rgb(var(--color-border) / 8%));
   border-radius: var(--radius-lg, 0.75rem);
   transition: border-color 0.15s ease, box-shadow 0.15s ease;
@@ -84,7 +84,7 @@
   transition: background 0.15s ease, border-color 0.15s ease;
 
   &:hover {
-    background: var(--hi-color-surface, rgba(240,244,248,0.95));
+    background: var(--hi-color-surface, rgba(255,255,255,0.95));
     border-color: rgb(var(--color-border) / 6%);
   }
 

package/src/components/HkLoadingVeil.scss

@@ -11,7 +11,7 @@
   justify-content: center;
   // Semi-transparent backdrop with a slight blur: the page beneath
   // stays readable (orientation) but clearly inactive.
-  background: rgb(var(--color-background, 214 236 240) / 0.55);
+  background: rgb(var(--color-background, 255 255 255) / 0.55);
   backdrop-filter: blur(6px);
   -webkit-backdrop-filter: blur(6px);
   pointer-events: all;
@@ -27,7 +27,7 @@
   gap: 12px;
   padding: 24px 32px;
   border-radius: 12px;
-  background: rgb(var(--color-surface, 240 244 248) / 0.85);
+  background: rgb(var(--color-surface, 255 255 255) / 0.85);
   box-shadow: 0 8px 32px rgb(0 0 0 / 0.12);
 }
 

package/src/components/HkMarkdownRenderer.scss

@@ -161,7 +161,7 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  background: color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 70%, transparent);
+  background: color-mix(in srgb, var(--hi-color-surface, #ffffff) 70%, transparent);
   backdrop-filter: blur(4px);
   z-index: 10;
 }

package/src/components/HkModal.scss

@@ -79,7 +79,7 @@
     height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
     max-height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
     clip-path var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
-  background: var(--hk-modal-bg, var(--hi-color-surface, rgba(240,244,248,0.95)));
+  background: var(--hk-modal-bg, var(--hi-color-surface, rgba(255,255,255,0.95)));
   backdrop-filter: var(--hk-modal-blur, none);
   border: 1px solid var(--hk-modal-border-color, var(--hi-color-border, rgba(100,100,100,0.08)));
   border-radius: var(--hk-modal-radius, var(--radius-lg, 12px));
@@ -323,7 +323,7 @@
     // covers never surface as foreign bands over the padding.
     background: var(
       --hk-scroll-pin-cover-bg,
-      var(--hk-modal-bg, var(--hi-color-surface, rgba(240, 244, 248, 0.95)))
+      var(--hk-modal-bg, var(--hi-color-surface, rgba(255, 255, 255, 0.95)))
     );
   }
 
@@ -391,7 +391,7 @@
   font-size: var(--text-2xs);
   letter-spacing: 0.04em;
   color: var(--hi-color-muted, #6c6c6c);
-  background: color-mix(in srgb, var(--hi-color-surface, rgba(240,244,248,0.95)) 78%, transparent);
+  background: color-mix(in srgb, var(--hi-color-surface, rgba(255,255,255,0.95)) 78%, transparent);
   border: 1px solid color-mix(in srgb, var(--hi-color-border, rgba(100,100,100,0.08)) 12%, transparent);
   border-radius: var(--radius-full, 9999px);
   backdrop-filter: blur(4px);
@@ -547,7 +547,7 @@
     backdrop-filter: var(--hk-modal-blur-mobile, none);
     background: var(
       --hk-modal-bg-mobile,
-      var(--hk-modal-bg, var(--hi-color-surface, rgba(240, 244, 248, 0.95)))
+      var(--hk-modal-bg, var(--hi-color-surface, rgba(255, 255, 255, 0.95)))
     );
     border-radius: var(--hk-modal-radius, var(--radius-lg, 12px))
                    var(--hk-modal-radius, var(--radius-lg, 12px))

package/src/components/HkModalBreadcrumb.scss

@@ -13,7 +13,7 @@
   // family don't collapse this strip (8px→4px gap, 32px→16px padding).
   gap: var(--space-8, 0.5rem);
   padding: var(--space-12, 0.75rem) var(--space-32, 2rem);
-  background: var(--hi-color-surface, rgba(240,244,248,0.95));
+  background: var(--hi-color-surface, rgba(255,255,255,0.95));
   border: 1px solid var(--hk-breadcrumb-border, rgba(0, 0, 0, 0.06));
   border-radius: var(--radius-md, 0.5rem);
   box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);

package/src/components/HkPasswordSurface.scss

@@ -342,6 +342,6 @@
 .hk-pwd-box input:-webkit-autofill:active {
   -webkit-text-fill-color: var(--hi-color-text-primary, #1e1e1e) !important;
   caret-color: var(--hi-color-text-primary, #1e1e1e);
-  box-shadow: 0 0 0 1000px var(--hi-color-surface, #f0f4f8) inset !important;
+  box-shadow: 0 0 0 1000px var(--hi-color-surface, #ffffff) inset !important;
   transition: background-color calc(infinity * 1s) step-end, color calc(infinity * 1s) step-end;
 }

package/src/components/HkRadio.scss

@@ -101,7 +101,7 @@
    :focus-visible keeps mouse clicks ring-free. */
 .hk-radio-box:has(.hk-radio-input:focus-visible) {
   box-shadow:
-    0 0 0 2px var(--hi-color-surface, rgba(240,244,248,0.95)),
+    0 0 0 2px var(--hi-color-surface, rgba(255,255,255,0.95)),
     0 0 0 4px var(--hi-color-primary, #7aa2f7);
 }
 

package/src/components/HkScrollContainer.scss

@@ -194,7 +194,7 @@
   font-size: var(--text-2xs);
   letter-spacing: 0.04em;
   color: var(--hi-color-muted, #6c6c6c);
-  background: color-mix(in srgb, var(--hi-color-surface, rgba(240,244,248,0.95)) 78%, transparent);
+  background: color-mix(in srgb, var(--hi-color-surface, rgba(255,255,255,0.95)) 78%, transparent);
   border: 1px solid color-mix(in srgb, var(--hi-color-border, rgba(100,100,100,0.08)) 12%, transparent);
   border-radius: var(--radius-full, 9999px);
   backdrop-filter: blur(4px);

package/src/components/HkScrollPin.scss

@@ -23,7 +23,7 @@
   // sticky header introduced; hosts retune through --hk-scroll-pin-bg).
   background: var(
     --hk-scroll-pin-bg,
-    color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 95%, transparent)
+    color-mix(in srgb, var(--hi-color-surface, #ffffff) 95%, transparent)
   );
   backdrop-filter: var(--hk-scroll-pin-blur, blur(6px));
 }

package/src/components/HkSidebar.scss

@@ -24,7 +24,7 @@
   display: flex;
   flex-direction: column;
   height: 100%;
-  background: var(--hk-sidebar-bg, var(--hi-color-surface, rgba(240,244,248,0.95)));
+  background: var(--hk-sidebar-bg, var(--hi-color-surface, rgba(255,255,255,0.95)));
   backdrop-filter: blur(var(--blur-sm, 8px));
   /* Logical edge: the border rides the content-facing side in either
    * direction (LTR sidebar docks left, RTL docks right). */

package/src/components/HkStepFlow.scss

@@ -30,7 +30,7 @@
   --hk-scroll-pin-z: var(--hk-stepflow-sticky-z, 10);
   --hk-scroll-pin-bg: var(
     --hk-stepflow-sticky-bg,
-    color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 95%, transparent)
+    color-mix(in srgb, var(--hi-color-surface, #ffffff) 95%, transparent)
   );
   // The HOST's declared gutter owns the resting offset, not this rule. The
   // pin contract's offset rule is (0,3,0) and parks a top pin at

package/src/components/HkStepGuide.scss

@@ -49,7 +49,7 @@
   padding: var(--space-20, 1.25rem);
   padding-block-start: calc(var(--space-20, 1.25rem) + var(--space-2, 0.125rem));
   border-radius: var(--radius-lg, 1rem);
-  background: var(--hi-color-surface, #f0f4f8);
+  background: var(--hi-color-surface, #ffffff);
 
   &[data-done] {
     box-shadow: inset 0 0 0 1px rgb(from var(--hi-color-success, #0eb840) r g b / 0.55);

package/src/components/HkSwitch.scss

@@ -29,7 +29,7 @@
    the label; house pattern: HkButton double ring). */
 .hk-switch-input:focus-visible ~ .hk-switch-track {
   box-shadow:
-    0 0 0 2px var(--hi-color-surface, rgba(240, 244, 248, 0.95)),
+    0 0 0 2px var(--hi-color-surface, rgba(255, 255, 255, 0.95)),
     0 0 0 4px var(--hi-color-primary, #7aa2f7);
 }
 

package/src/components/HkTag.scss

@@ -58,7 +58,7 @@
 }
 
 .hk-tag-default {
-  background: color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 60%, transparent);
+  background: color-mix(in srgb, var(--hi-color-surface, #ffffff) 60%, transparent);
   color: var(--hi-color-text-primary, #1e1e1e);
   border-color: var(--hi-color-border, #646464);
 }

package/src/components/HkTitleBar.scss

@@ -7,7 +7,7 @@
 
 .hk-titlebar {
   --hk-tb-height: 32px;
-  --hk-tb-bg: color-mix(in srgb, rgb(var(--color-surface, 240 244 248)) 80%, transparent);
+  --hk-tb-bg: color-mix(in srgb, rgb(var(--color-surface, 255 255 255)) 80%, transparent);
   --hk-tb-border: rgb(var(--color-border, 100 100 100) / 0.25);
   --hk-tb-fg: rgb(var(--color-text-secondary, 102 102 102));
   --hk-tb-fg-strong: rgb(var(--color-text, 30 30 30));

package/src/components/HkTransitionContainer.scss

@@ -0,0 +1,13 @@
+// HkTransitionContainer — the state-keyed morph container. The host
+// carries the inline size (transitioned by the component); the stage
+// is the measured content. Overflow hides DURING the morph only (the
+// host is `overflow: clip` while a pinned size is active — applied via
+// the inline width/height, the clip rides along) so shortened content
+// never spills past the animating box.
+.hk-tc {
+  overflow: clip;
+}
+
+.hk-tc-stage {
+  width: 100%;
+}

package/src/components/HkTransitionContainer.test.tsx

@@ -0,0 +1,127 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, ref, type App } from "vue";
+
+import HkTransitionContainer from "./HkTransitionContainer";
+import {
+  DEFAULT_ANIMATION_DURATION_MS,
+  animationLoopArmedCount,
+  onAnimationFrame,
+} from "../composables/useAnimationLoop";
+
+/** Shared-container discipline (HkCrossfade.test precedent): every
+ *  case appends its own container; afterEach tears them all down. */
+const containers: HTMLElement[] = [];
+
+interface Harness {
+  app: App;
+  container: HTMLElement;
+  key: { value: string };
+  swaps: Array<{ key: string | number; previous: string | number; durationMs: number }>;
+}
+
+function mountContainer(initial = "a"): Harness {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const key = ref(initial);
+  const swaps: Harness["swaps"] = [];
+  const Wrapper = defineComponent({
+    setup() {
+      return () => (
+        <HkTransitionContainer
+          swapKey={key.value}
+          onSwap={(e: { key: string | number; previous: string | number; durationMs: number }) => {
+            swaps.push(e);
+          }}
+        >
+          <p>{`panel-${key.value}`}</p>
+        </HkTransitionContainer>
+      );
+    },
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  return { app, container, key, swaps };
+}
+
+afterEach(() => {
+  for (const c of containers.splice(0)) c.remove();
+});
+
+describe("HkTransitionContainer", () => {
+  it("renders the slot inside the morph host", () => {
+    const t = mountContainer("a");
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    const stage = t.container.querySelector<HTMLElement>(".hk-tc-stage");
+    expect(host).not.toBeNull();
+    expect(stage).not.toBeNull();
+    expect(t.container.textContent).toContain("panel-a");
+    t.app.unmount();
+  });
+
+  it("defaults to the 300ms family duration on the host transition", () => {
+    const t = mountContainer("a");
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.transitionDuration).toBe(`${DEFAULT_ANIMATION_DURATION_MS}ms`);
+    expect(DEFAULT_ANIMATION_DURATION_MS).toBe(300);
+    t.app.unmount();
+  });
+
+  it("axis=width transitions only the width property", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const app = createApp({
+      render: () => (
+        <HkTransitionContainer swapKey="a" axis="width">
+          <p>x</p>
+        </HkTransitionContainer>
+      ),
+    });
+    app.mount(container);
+    const host = container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.transitionProperty).toBe("width");
+    app.unmount();
+  });
+
+  it("survives a swapKey change without ResizeObserver (degraded path, no NaN)", async () => {
+    const t = mountContainer("login");
+    t.key.value = "org";
+    await new Promise((r) => setTimeout(r, DEFAULT_ANIMATION_DURATION_MS + 120));
+    // jsdom has no ResizeObserver and zero offsets: no morph, no crash,
+    // and any pinned inline size is well-formed (never NaNpx).
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.width).not.toContain("NaN");
+    expect(host?.style.height).not.toContain("NaN");
+    t.app.unmount();
+  });
+});
+
+describe("useAnimationLoop (shared rAF context)", () => {
+  it("registers and unregisters; the loop idles at zero", () => {
+    const cb = vi.fn();
+    const off = onAnimationFrame(cb);
+    expect(animationLoopArmedCount()).toBe(1);
+    off();
+    expect(animationLoopArmedCount()).toBe(0);
+  });
+
+  it("dedupes the same callback registration", () => {
+    const cb = vi.fn();
+    const off1 = onAnimationFrame(cb);
+    const off2 = onAnimationFrame(cb);
+    expect(animationLoopArmedCount()).toBe(1);
+    off1();
+    expect(animationLoopArmedCount()).toBe(0);
+    off2();
+    expect(animationLoopArmedCount()).toBe(0);
+  });
+
+  it("unregister is idempotent", () => {
+    const cb = vi.fn();
+    const off = onAnimationFrame(cb);
+    off();
+    off();
+    expect(animationLoopArmedCount()).toBe(0);
+  });
+});

package/src/components/HkTransitionContainer.tsx

@@ -0,0 +1,154 @@
+import { defineComponent, nextTick, onBeforeUnmount, ref, watch, type PropType } from "vue";
+
+import { DEFAULT_ANIMATION_DURATION_MS } from "../composables/useAnimationLoop";
+import HkCrossfade from "./HkCrossfade";
+
+import "./HkTransitionContainer.scss";
+
+/**
+ * HkTransitionContainer — the state-keyed morph container.
+ *
+ * HkCrossfade's height-safe dissolve, PLUS the size choreography the
+ * user direction (2026-10-22) asks of every swap surface: when the
+ * bound state key changes, the OLD content fades out, the container's
+ * width/height smoothly animate to the incoming content's natural
+ * size, and the NEW content fades in — one 300ms default, CSS-driven
+ * (transition on inline size), with the animation-loop registration
+ * kept for the choreography CSS cannot express.
+ *
+ * Binding: `swapKey` is the identity of the content on stage — the same
+ * contract HkCrossfade owns (same value ⇒ no swap). Tabs, segmented
+ * controls, editor mode switches, chat-node state labels all reduce to
+ * "a key changed; morph to the new panel".
+ *
+ * Scroll handoff (loose coupling, per the user's spec): the container
+ * never touches any scroller itself. Each swap emits a `swap` event
+ * carrying `{ key, previous, durationMs }`; the HOST forwards that to
+ * its scroll container's PUBLIC interface — the same scrollTo API used
+ * for back-to-top and jump-to-line — so the scrollbar adapts to the
+ * size change and the caret/anchor coordinate glides instead of
+ * teleporting. The scroll container needs zero knowledge of this
+ * component.
+ *
+ * Sizing: a ResizeObserver on the inner stage feeds the container's
+ * inline width/height; the CSS transition on those properties does the
+ * actual morph (off-thread, cancellable, respects the global animation
+ * switch via the duration override to 0s). When the observer is
+ * unavailable (older webview, SSR, jsdom) the container degrades to
+ * plain auto sizing — a dissolve without the morph, never a broken
+ * layout.
+ */
+export default defineComponent({
+  name: "HkTransitionContainer",
+  props: {
+    /** Identity of the content on stage; changing it starts the morph. */
+    swapKey: { type: [String, Number] as PropType<string | number>, required: true },
+    /** Which axes morph. `height` is the default (most swap surfaces);
+     * `width` for horizontal morphs (segmented panels); `both` for
+     * free-floating cards. */
+    axis: {
+      type: String as PropType<"height" | "width" | "both">,
+      default: "height",
+    },
+    /** Morph + dissolve duration, ms. Family default 300. */
+    duration: { type: Number, default: DEFAULT_ANIMATION_DURATION_MS },
+    tag: { type: String, default: "div" },
+  },
+  emits: {
+    /** Fired when a swap settles: the host forwards this to its scroll
+     * container's public scrollTo interface. */
+    swap: (payload: { key: string | number; previous: string | number; durationMs: number }) => true,
+  },
+  setup(props, { slots, emit }) {
+    const hostRef = ref<HTMLElement | null>(null);
+    const stageRef = ref<HTMLElement | null>(null);
+    // Pinned inline size: `{ w, h }` while morphing, `null` = auto.
+    const pinned = ref<{ w: number; h: number } | null>(null);
+
+    let observer: ResizeObserver | null = null;
+    let pendingKey: string | number | null = null;
+    let settleTimer: ReturnType<typeof setTimeout> | null = null;
+
+    function readStage(): { w: number; h: number } {
+      const el = stageRef.value;
+      if (!el) return { w: 0, h: 0 };
+      return { w: el.offsetWidth, h: el.offsetHeight };
+    }
+
+    function applyPinned(): void {
+      const el = hostRef.value;
+      if (!el) return;
+      const p = pinned.value;
+      el.style.width = p && props.axis !== "height" ? `${p.w}px` : "";
+      el.style.height = p && props.axis !== "width" ? `${p.h}px` : "";
+    }
+
+    function observe(): void {
+      if (typeof ResizeObserver === "undefined" || !stageRef.value) return;
+      observer?.disconnect();
+      observer = new ResizeObserver((entries) => {
+        const rect = entries[0]?.contentRect;
+        if (!rect || pendingKey === null) return;
+        // Stage settled at the incoming content's natural size: pin to
+        // it (from the outgoing size) → next frame the CSS transition
+        // morphs the container; after the duration, release to auto.
+        pinned.value = { w: Math.ceil(rect.width), h: Math.ceil(rect.height) };
+        applyPinned();
+        if (settleTimer !== null) clearTimeout(settleTimer);
+        settleTimer = setTimeout(() => {
+          pinned.value = null;
+          applyPinned();
+          const key = pendingKey;
+          pendingKey = null;
+          if (key !== null) {
+            emit("swap", { key, previous: previousKey, durationMs: props.duration });
+          }
+        }, props.duration + 40);
+      });
+      observer.observe(stageRef.value);
+    }
+
+    let previousKey: string | number = props.swapKey;
+
+    watch(() => props.swapKey, (next) => {
+      // Pin the OUTGOING size first so the container never collapses
+      // through zero while the content swaps underneath.
+      pendingKey = next;
+      pinned.value = readStage();
+      applyPinned();
+      void nextTick(() => observe());
+    });
+
+    onBeforeUnmount(() => {
+      observer?.disconnect();
+      observer = null;
+      if (settleTimer !== null) clearTimeout(settleTimer);
+    });
+
+    return () => {
+      const Tag = props.tag as "div" | "section" | "main" | "aside";
+      const d = `${props.duration}ms`;
+      return (
+        <Tag
+          ref={hostRef}
+          class="hk-tc"
+          style={{
+            transitionProperty:
+              props.axis === "both" ? "width, height" : props.axis === "width" ? "width" : "height",
+            transitionDuration: d,
+          }}
+        >
+          {/* The stage is HkCrossfade: it owns the opacity dissolve
+            (both generations stacked in one grid cell — no exit blank,
+            no collapse flash) and the swap-stall watchdog; THIS
+            component owns the measured size morph around it. */}
+          <div ref={stageRef} class="hk-tc-stage">
+            <HkCrossfade swapKey={props.swapKey}>
+              {slots.default?.()}
+            </HkCrossfade>
+          </div>
+        </Tag>
+      );
+    };
+  },
+});

package/src/components/HkTree.scss

@@ -114,7 +114,7 @@
   cursor: pointer;
 
   &:hover {
-    background: color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 40%, transparent);
+    background: color-mix(in srgb, var(--hi-color-surface, #ffffff) 40%, transparent);
     color: var(--hi-color-text-primary, #1e1e1e);
   }
 }

package/src/components/HkUserPicker.scss

@@ -25,7 +25,7 @@
   gap: var(--space-8, 0.5rem);
   min-height: 2.5rem;
   padding: var(--space-8, 0.5rem) var(--space-12, 0.75rem);
-  background: var(--hi-color-surface, rgba(240, 244, 248, 0.95));
+  background: var(--hi-color-surface, rgba(255, 255, 255, 0.95));
   border: 1px solid var(--hk-kw-border, rgb(var(--color-border) / 8%));
   border-radius: var(--radius-lg, 0.75rem);
   cursor: pointer;

package/src/composables/useAnimationLoop.ts

@@ -0,0 +1,95 @@
+/**
+ * useAnimationLoop — the family's ONE shared requestAnimationFrame loop.
+ *
+ * Every JS-driven animation in the library registers a callback here
+ * instead of opening its own rAF chain: the context owns a single loop
+ * that runs ONLY while at least one callback is registered, and each
+ * frame dispatches `(now, deltaMs)` to every callback that was armed at
+ * frame start (a callback that registers/unregisters mid-frame takes
+ * effect next frame — the iteration walks a snapshot). CSS transitions
+ * remain the preferred vehicle (the browser composites them
+ * off-thread); this loop is for the choreography CSS cannot express —
+ * measured size morphs, staged state sequences, scroll handshakes
+ * (user direction 2026-10-22).
+ *
+ * The family-wide default duration for BOTH CSS and loop-driven
+ * animation is 300ms (`DEFAULT_ANIMATION_DURATION_MS`), matching the
+ * design system's `--duration-normal` token — one number, everywhere.
+ */
+
+/** The family-wide animation default: 300ms (== `--duration-normal`). */
+export const DEFAULT_ANIMATION_DURATION_MS = 300;
+
+/** First-frame delta stand-in: one 60Hz frame. */
+const DEFAULT_FRAME_DELTA_MS = 1000 / 60;
+
+/** A per-frame callback: absolute rAF timestamp + ms since last frame. */
+export type AnimationFrameCallback = (nowMs: number, deltaMs: number) => void;
+
+interface LoopState {
+  callbacks: Set<AnimationFrameCallback>;
+  handle: number | null;
+  last: number | null;
+}
+
+// Module-level singleton: one loop per document, however many consumers.
+const state: LoopState = { callbacks: new Set(), handle: null, last: null };
+
+function engine(nowMs: number): void {
+  // Snapshot BEFORE mutating state: mid-frame (un)registrations land
+  // next frame, and a callback never runs twice inside one frame.
+  const armed = Array.from(state.callbacks);
+  const prev = state.last;
+  if (armed.length > 0) {
+    state.handle = requestAnimationFrame(engine);
+    state.last = nowMs;
+  } else {
+    state.handle = null;
+    state.last = null;
+  }
+  const delta = prev === null ? DEFAULT_FRAME_DELTA_MS : Math.max(0, nowMs - prev);
+  for (const cb of armed) cb(nowMs, delta);
+}
+
+/**
+ * Register a per-frame callback. Returns the unregister function; call
+ * it when the animation settles (or the component unmounts). Registering
+ * the SAME function twice is idempotent (Set semantics). The loop is
+ * lazily started by the first registration and stops itself the moment
+ * the last callback unregisters — idle pages pay zero rAF churn.
+ */
+export function onAnimationFrame(cb: AnimationFrameCallback): () => void {
+  state.callbacks.add(cb);
+  if (state.handle === null) {
+    state.last = null;
+    state.handle = requestAnimationFrame(engine);
+  }
+  return () => {
+    state.callbacks.delete(cb);
+    if (state.callbacks.size === 0 && state.handle !== null) {
+      cancelAnimationFrame(state.handle);
+      state.handle = null;
+      state.last = null;
+    }
+  };
+}
+
+/** Test/introspection hook: how many callbacks are armed right now. */
+export function animationLoopArmedCount(): number {
+  return state.callbacks.size;
+}
+
+/**
+ * Component-facing wrapper: one registration bound to one callback
+ * (register on creation, `dispose()` when the owner unmounts). The
+ * callback receives `(nowMs, deltaMs)` every frame while armed.
+ */
+export function useAnimationLoop(cb: AnimationFrameCallback): { dispose: () => void } {
+  let off: (() => void) | null = onAnimationFrame(cb);
+  return {
+    dispose(): void {
+      off?.();
+      off = null;
+    },
+  };
+}

package/src/index.ts

@@ -613,6 +613,7 @@ export { default as HkColorPicker } from "./components/HkColorPicker";
 export { default as HkCopyBadge } from "./components/HkCopyBadge";
 export { default as HkConfirmDialog } from "./components/HkConfirmDialog";
 export { default as HkCrossfade } from "./components/HkCrossfade";
+export { default as HkTransitionContainer } from "./components/HkTransitionContainer";
 export { default as HkDivider } from "./components/HkDivider";
 export { default as HkDiffViewer } from "./components/HkDiffViewer";
 export { parseUnifiedDiff, computeGaps } from "./components/diffParse";

package/src/styles/admin-tokens.scss

@@ -23,7 +23,7 @@
   /* ── Hikari color bridge ─ */
   --hi-color-primary: rgb(var(--color-primary, 122 162 247));
   --hi-color-primary-rgb: var(--color-primary, 122 162 247);
-  --hi-color-surface: rgb(var(--color-surface, 240 244 248));
+  --hi-color-surface: rgb(var(--color-surface, 255 255 255));
   --hi-color-border: rgb(var(--color-border, 100 100 100) / 15%);
   --hi-color-text-primary: rgb(var(--color-text, 30 30 30));
   --hi-color-text-on-primary: rgb(var(--color-on-primary, 255 255 255)); /* deprecated in-tree: prefer the on-solid slots */
@@ -34,11 +34,11 @@
   --hi-color-icon-on-solid: rgb(var(--color-on-solid-icon, 255 255 255));
   --hi-color-text-secondary: color-mix(in srgb, rgb(var(--color-text, 30 30 30)) 60%, transparent);
   --hi-color-muted: rgb(var(--color-muted, 108 108 108));
-  --hi-color-background: rgb(var(--color-background, 214 236 240));
-  --hi-color-bg-canvas: rgb(var(--color-background, 214 236 240));
-  --hi-color-bg-elevated: rgb(var(--color-surface, 240 244 248));
-  --hi-color-bg-subtle: rgb(var(--color-surface, 240 244 248) / 0.5);
-  --hi-secondary-bg: rgb(var(--color-surface, 240 244 248) / 0.5);
+  --hi-color-background: rgb(var(--color-background, 255 255 255));
+  --hi-color-bg-canvas: rgb(var(--color-background, 255 255 255));
+  --hi-color-bg-elevated: rgb(var(--color-surface, 255 255 255));
+  --hi-color-bg-subtle: rgb(var(--color-surface, 255 255 255) / 0.5);
+  --hi-secondary-bg: rgb(var(--color-surface, 255 255 255) / 0.5);
   --hi-color-danger: rgb(var(--color-error, 247 118 142));
   --hi-color-success: rgb(var(--color-success, 14 184 64));
   --hi-color-warning: rgb(var(--color-warning, 238 214 119));
@@ -58,7 +58,7 @@
    * by load order. (--hk-surface's only in-tree consumer — the retired
    * HTabs tail overlay — is gone; the token stays published for
    * external plana-ui readers.) */
-  --hk-surface: var(--color-surface, 240 244 248);
+  --hk-surface: var(--color-surface, 255 255 255);
   --hk-primary: var(--color-primary, 122 162 247);
 }
 
@@ -948,7 +948,7 @@
      depend on the host having loaded the reset sheet (without it a 1px
      border pushes the box 2px past its max-width and off-centre). */
   box-sizing: border-box;
-  background: color-mix(in srgb, rgb(var(--color-surface, 240 244 248)) 70%, transparent);
+  background: color-mix(in srgb, rgb(var(--color-surface, 255 255 255)) 70%, transparent);
   border: 1px solid color-mix(in srgb, rgb(var(--color-text, 30 30 30)) 12%, transparent);
   border-radius: var(--hi-radius-sm, 4px);
   box-shadow: 0 2px 16px rgb(0 0 0 / 8%);
@@ -1207,11 +1207,11 @@
 }
 
 .a-bg-secondary {
-  background: rgb(var(--color-background, 214 236 240));
+  background: rgb(var(--color-background, 255 255 255));
 }
 
 .a-bg-tertiary {
-  background: rgb(var(--color-surface, 240 244 248));
+  background: rgb(var(--color-surface, 255 255 255));
 }
 
 .a-latency-text {

package/src/styles/theme/channels.scss

@@ -93,8 +93,14 @@
   --color-muted: 108 108 108;
   --color-border: 100 100 100;
   --color-focused-border: 122 162 247;
-  --color-background: 214 236 240;
-  --color-surface: 240 244 248;
+  /* Static seed floor (2026-10-22 user direction): pure white — the
+   * pale-cyan paper default retired. These seeds are the PRE-ENGINE
+   * paint (and the engine-failure floor); the runtime theme overrides
+   * them on :root once JS applies a preset (dark mode included — the
+   * engine owns scheme switching, the seeds are the light default). */
+  --color-background: 255 255 255;
+  --color-surface: 255 255 255;
+
   /* Derived seed defaults for the runtime-selected channels: a primary
    * wash over the background (selected) and the surface tint (status
    * bar), matching what presets derive at runtime. */

package/src/tokens.scss

@@ -86,8 +86,14 @@
   --color-muted: 108 108 108;
   --color-border: 100 100 100;
   --color-focused-border: 122 162 247;
-  --color-background: 214 236 240;
-  --color-surface: 240 244 248;
+  /* Static seed floor (2026-10-22 user direction): pure white — the
+   * pale-cyan paper default retired. These seeds are the PRE-ENGINE
+   * paint (and the engine-failure floor); the runtime theme overrides
+   * them on :root once JS applies a preset (dark mode included — the
+   * engine owns scheme switching, the seeds are the light default). */
+  --color-background: 255 255 255;
+  --color-surface: 255 255 255;
+
   /* Derived seed defaults for the runtime-selected channels: a primary
    * wash over the background (selected) and the surface tint (status
    * bar), matching what presets derive at runtime. */