@celestia-island/hikari 0.55.70 → 0.55.72

package/package.json

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

package/src/components/HkTimeline.scss

@@ -441,10 +441,9 @@
 }
 
 // ── Navigation motion (2026-09-23 user directive, round 16) ──────────
-// The stepper never hard-cuts: status colors crossfade, the full-mode
-// active halo slides between step nodes, and the window-mode cells wipe
-// in from the navigation side. All of it rides the family's standard
-// duration/ease and collapses under reduced motion.
+// The stepper never hard-cuts: status colors crossfade and the window-mode
+// cells wipe in from the navigation side. All of it rides the family's
+// standard duration/ease and collapses under reduced motion.
 
 .hk-timeline {
   --hk-timeline-motion: 0.3s;
@@ -462,41 +461,17 @@
     border-color var(--hk-timeline-motion) var(--hk-timeline-motion-ease);
 }
 
-// Full mode: the active halo — a measured pill behind the active step
-// (the component positions it via transform/size), sliding between
-// nodes with the same clock. The first placement is instant (data-placed
-// gates the transition) so opening the sheet does not animate it.
+// The full-mode active halo was removed here (2026-09-24 user directive):
+// a measured pill behind the active step, sliding between nodes, which
+// read as an unexplained primary blob in every wide multi-step flow and
+// duplicated what the filled indicator and the label weight already say.
+// Window mode never had one. The containing-block rule below stays — it is
+// the timeline's anchor for any absolutely positioned consumer content, and
+// the vertical rail anchors to the step rather than to this box.
 .hk-timeline[data-mode="full"]:not(.hk-scroll-pin) {
   position: relative;
 }
 
-.hk-timeline-halo {
-  position: absolute;
-  left: 0;
-  top: 50%;
-  translate: 0 -50%;
-  border-radius: 999px;
-  background: color-mix(in srgb, var(--hi-color-primary) 10%, transparent);
-  pointer-events: none;
-  height: 100%;
-  box-sizing: border-box;
-}
-
-.hk-timeline[data-orientation="vertical"] .hk-timeline-halo {
-  top: 0;
-  left: 50%;
-  translate: -50% 0;
-  width: 100%;
-  height: auto;
-}
-
-.hk-timeline-halo[data-placed] {
-  transition:
-    transform var(--hk-timeline-motion) var(--hk-timeline-motion-ease),
-    width var(--hk-timeline-motion) var(--hk-timeline-motion-ease),
-    height var(--hk-timeline-motion) var(--hk-timeline-motion-ease);
-}
-
 // Window mode: each cell's step content is keyed by its step key, so a
 // navigation remounts it — wipe in from the navigation side. data-dir is
 // absent on the very first render, so opening does not animate.
@@ -562,8 +537,4 @@ html[data-css-animations="0"] .hk-timeline[data-mode="window"][data-dir] .hk-tim
   .hk-timeline[data-mode="window"][data-dir] .hk-timeline-step {
     animation: none;
   }
-
-  .hk-timeline-halo[data-placed] {
-    transition: none;
-  }
 }

package/src/components/HkTimeline.test.tsx

@@ -424,36 +424,20 @@ describe("HkTimeline navigation motion (round 16)", () => {
     return { container, current };
   }
 
-  it("positions the full-mode halo on the active step and slides it on navigation", async () => {
-    const { container, current } = mountTimeline(4, "s1");
-    // happy-dom has no layout engine: give the step nodes deterministic
-    // offsets so the halo's measured transform is observable.
-    const steps = () =>
-      Array.from(container.querySelectorAll<HTMLElement>(".hk-timeline-step"));
-    for (const [i, step] of steps().entries()) {
-      Object.defineProperty(step, "offsetLeft", {
-        configurable: true,
-        get: () => i * 100,
-      });
-      Object.defineProperty(step, "offsetWidth", {
-        configurable: true,
-        get: () => 80,
-      });
-    }
-    await nextTick();
-    await nextTick();
-    const halo = container.querySelector<HTMLElement>(".hk-timeline-halo");
-    expect(halo).not.toBeNull();
-    // Active = s1 (second node): translateX(100 - pad).
-    expect(halo!.style.transform).toBe("translateX(94px)");
-    expect(halo!.style.width).toBe("92px");
-    expect(halo!.hasAttribute("data-placed")).toBe(true);
-
-    current.value = "s3";
+  it("renders no full-mode halo behind the active step", async () => {
+    // The measured pill that used to slide behind the active step is gone
+    // (2026-09-24 user directive): in a wide multi-step flow it read as an
+    // unexplained primary blob, and the filled indicator plus the label
+    // weight already carry the active step. Pinned so a later "highlight"
+    // refactor cannot quietly reintroduce it.
+    const { container } = mountTimeline(4, "s1");
     await nextTick();
     await nextTick();
-    // Slid to the fourth node.
-    expect(halo!.style.transform).toBe("translateX(294px)");
+    expect(container.querySelector(".hk-timeline-halo")).toBeNull();
+    // The overlay the window mode owns is a different element and stays a
+    // window-mode concern — full mode draws its connectors inline.
+    expect(container.querySelector(".hk-timeline[data-mode='full']")).not.toBeNull();
+    expect(container.querySelector(".hk-timeline-links")).toBeNull();
   });
 
   it("marks the navigation direction for the window-mode wipe", async () => {

package/src/components/HkTimeline.tsx

@@ -178,9 +178,8 @@ export default defineComponent({
 
     // ── Navigation motion (2026-09-23 user directive, round 16) ──────
     // The stepper must not hard-cut between steps: the status colors
-    // crossfade (stylesheet), the window-mode cells wipe in from the
-    // navigation side (keyed remount + data-dir), and the full-mode
-    // active halo slides between step nodes (measured transform).
+    // crossfade (stylesheet) and the window-mode cells wipe in from the
+    // navigation side (keyed remount + data-dir).
     let prevIndex = currentIndex.value;
     /** Set once the first navigation revealed a direction; drives the
      *  window-mode wipe's side via the host attribute. */
@@ -192,37 +191,11 @@ export default defineComponent({
       prevIndex = idx;
     });
 
-    /** The sliding full-mode highlight. */
-    const halo = ref<HTMLElement | null>(null);
-    function positionHalo(): void {
-      const hostEl = host.value;
-      const haloEl = halo.value;
-      if (!hostEl || !haloEl) return;
-      const step = hostEl.querySelector<HTMLElement>(
-        '.hk-timeline-step[data-status="active"]',
-      );
-      if (!step) return;
-      const vertical = props.orientation === "vertical";
-      const pad = 6;
-      if (vertical) {
-        haloEl.style.transform = `translateY(${Math.max(0, step.offsetTop - pad)}px)`;
-        haloEl.style.width = "";
-        haloEl.style.height = `${step.offsetHeight + pad * 2}px`;
-      } else {
-        haloEl.style.transform = `translateX(${Math.max(0, step.offsetLeft - pad)}px)`;
-        haloEl.style.height = "";
-        haloEl.style.width = `${step.offsetWidth + pad * 2}px`;
-      }
-      // The very first placement must not animate from nothing — only
-      // subsequent moves ride the CSS transition.
-      haloEl.setAttribute("data-placed", "");
-    }
-    watch(
-      () => [props.currentKey, props.orientation] as const,
-      () => {
-        void nextTick(positionHalo);
-      },
-    );
+    // The sliding full-mode highlight is gone (2026-09-24 user directive).
+    // It read as an unexplained primary blob behind the active step in every
+    // multi-step flow that is wide enough to show all of them, and the
+    // active step is already carried by its filled indicator plus the label
+    // weight. Window mode never had one, so nothing replaces it there.
 
     function statusOf(idx: number): TimelineStepStatus {
       return idx < currentIndex.value
@@ -262,13 +235,11 @@ export default defineComponent({
       if (typeof ResizeObserver !== "undefined") {
         observer = new ResizeObserver(() => {
           measure();
-          positionHalo();
         });
         if (host.value) observer.observe(host.value);
       }
       void nextTick(() => {
         measure();
-        positionHalo();
       });
     });
 
@@ -428,7 +399,6 @@ export default defineComponent({
           data-mode="full"
           data-dir={navDir.value ?? undefined}
         >
-          <div ref={halo} class="hk-timeline-halo" aria-hidden="true" />
           {props.steps.map((_step, idx) => {
             const isLast = idx === props.steps.length - 1;
             return renderStep(idx, { connector: !isLast, last: isLast });

package/src/components/HkWallpaperBackdrop.styles.contract.test.ts

@@ -184,7 +184,8 @@ describe("HkWallpaperBackdrop.tsx — no page-global DOM writes", () => {
   });
 
   it("does not read chest's fixed element ids", () => {
-    // The registry + legacy fallback live in the theme layer, not here.
+    // The surface registry lives in the theme layer, not here — and since the
+    // legacy id fallback was retired it is the only way in.
     expect(stripComments(tsx)).not.toContain("s-wallpaper-");
   });
 });

package/src/components/HkWallpaperBackdrop.tsx

@@ -381,9 +381,10 @@ export default defineComponent({
     });
 
     onMounted(() => {
-      // Registered BEFORE the first sample: the sampler resolves its source
-      // through this registry, and an unregistered instance falls back to
-      // the legacy element ids (the pre-component contract).
+      // Registered BEFORE the first sample: registration is the sampler's
+      // only way to find a wallpaper surface — an instance that has not
+      // registered is invisible to it, and the sample falls through to the
+      // body background.
       unregisterSources = registerWallpaperSurfaceSources({
         canvas: () => canvasRef.value,
         video: () => videoRef.value,

package/src/index.ts

@@ -219,7 +219,7 @@ export {
   themeDecorVersion, isThemeDecorSlot, THEME_DECOR_SLOT_PATTERN, THEME_DECOR_WILDCARD,
   allGroupSlots, resolveLocalizedText, parseTokenGroupConfig, registerTokenGroupConfig,
   startLuminanceSampler, stopLuminanceSampler, sampleLuminanceNow, invalidateLuminanceCache,
-  registerWallpaperSurfaceSources, resolveWallpaperSurfaceElement, LEGACY_WALLPAPER_SURFACE_IDS,
+  registerWallpaperSurfaceSources, resolveWallpaperSurfaceElement,
   retainLuminanceSampler, releaseLuminanceSampler, luminanceSamplerRefCount,
   type WallpaperSurfaceKind, type WallpaperSurfaceSources,
   getTimePeriod, getGeolocation, solarAltitude, DEFAULT_GEO_LOCATION,
@@ -603,3 +603,162 @@ export {
   type DialCodeEntry,
   type ParsedE164,
 } from "./data/dialCodes";
+
+// ── Canonical Hk* names (2026-09-24 unification) ─────────────────────
+// Every public name now exists in both spellings: the historical H*
+// aliases above (deprecated — migrate to the Hk* forms) and the Hk*
+// canonical names below, which match the source file names. Consumers
+// migrate at their own pace; the H* aliases are removed only after the
+// last consumer stops using them. Components export under the name of
+// their source file; named exports whose source identifier was already
+// Hk-prefixed now export that identifier unaliased.
+
+export { default as HkActionBar } from "./components/HkActionBar";
+export { default as HkAdaptiveDialog } from "./components/HkAdaptiveDialog";
+export { default as HkAlert } from "./components/HkAlert";
+export { default as HkAltSignIn } from "./components/HkAltSignIn";
+export { default as HkAvatar } from "./components/HkAvatar";
+export { default as HkBadge } from "./components/HkBadge";
+export { default as HkBoard } from "./components/HkBoard";
+export { default as HkBlockingToast } from "./components/HkBlockingToast";
+export { default as HkBreadcrumb } from "./components/HkBreadcrumb";
+export { default as HkButton } from "./components/HkButton";
+export { default as HkCard } from "./components/HkCard";
+export { default as HkCheckbox } from "./components/HkCheckbox";
+export { default as HkColorPicker } from "./components/HkColorPicker";
+export { default as HkConfirmDialog } from "./components/HkConfirmDialog";
+export { default as HkCrossfade } from "./components/HkCrossfade";
+export { default as HkDivider } from "./components/HkDivider";
+export { default as HkDockBar } from "./components/HkDockBar";
+export { default as HkDrawer } from "./components/HkDrawer";
+export { default as HkEmptyState } from "./components/HkEmptyState";
+export { default as HkExpansionPanel } from "./components/HkExpansionPanel";
+export { default as HkFab } from "./components/HkFab";
+export { default as HkIcon } from "./components/HkIcon";
+export { default as HkIconButton } from "./components/HkIconButton";
+export { default as HkIconButtonGroup } from "./components/HkIconButtonGroup";
+export { default as HkImageLightbox } from "./components/HkImageLightbox";
+export { default as HkImagePreview } from "./components/HkImagePreview";
+export { default as HkInput } from "./components/HkInput";
+export { default as HkPlaceholderMarquee } from "./components/HkPlaceholderMarquee";
+export { default as HkKbd } from "./components/HkKbd";
+export { default as HkLabel } from "./components/HkLabel";
+export { default as HkListTransition } from "./components/HkListTransition";
+export { default as HkLoadMore } from "./components/HkLoadMore";
+export { default as HkMarkdownRenderer } from "./components/HkMarkdownRenderer";
+export { default as HkModal } from "./components/HkModal";
+export { default as HkNavItem } from "./components/HkNavItem";
+export { default as HkNumberInput } from "./components/HkNumberInput";
+export { default as HkPhoneInput } from "./components/HkPhoneInput";
+export { default as HkAffixPicker } from "./components/HkAffixPicker";
+export { default as HkPhaseTransition } from "./components/HkPhaseTransition";
+export { default as HkGaugeRing } from "./components/HkGaugeRing";
+export { default as HkProgressRing } from "./components/HkProgressRing";
+export { default as HkQrCode } from "./components/HkQrCode";
+export { default as HkRollingNumber } from "./components/HkRollingNumber";
+export { default as HkLocalePickerPopup } from "./components/HkLocalePickerPopup";
+export { default as HkHoverRevealAction } from "./components/HkHoverRevealAction";
+export { default as HkKeywordSearchModal } from "./components/HkKeywordSearchModal";
+export { default as HkModalBreadcrumb } from "./components/HkModalBreadcrumb";
+export { default as HkPopover } from "./components/HkPopover";
+export { default as HkMenu } from "./components/HkMenu";
+export { default as HkContextMenuProvider } from "./components/HkContextMenuProvider";
+export { default as HkMenuPanel } from "./components/HkMenuPanel";
+export { default as HkMenuActionItem } from "./components/HkMenuActionItem";
+export { default as HkMenuIdentityItem } from "./components/HkMenuIdentityItem";
+export { default as HkPopupSelect } from "./components/HkPopupSelect";
+export { default as HkProgressBar } from "./components/HkProgressBar";
+export { default as HkProgressDialog } from "./components/HkProgressDialog";
+export { default as HkRadio } from "./components/HkRadio";
+export { default as HkScrollContainer } from "./components/HkScrollContainer";
+export { default as HkSearchInput } from "./components/HkSearchInput";
+export { default as HkSplash } from "./components/HkSplash";
+export { default as HkSelect } from "./components/HkSelect";
+export { default as HkSelectPanel } from "./components/HkSelectPanel";
+export { default as HkSidebar } from "./components/HkSidebar";
+export { default as HkSkeleton } from "./components/HkSkeleton";
+export { default as HkSkeletonList } from "./components/HkSkeletonList";
+export { default as HkSlider } from "./components/HkSlider";
+export { default as HkSpinner } from "./components/HkSpinner";
+export { default as HkSwitch } from "./components/HkSwitch";
+export { default as HkTable } from "./components/HkTable";
+export { default as HkTabs } from "./components/HkTabs";
+export { default as HkTag } from "./components/HkTag";
+export { default as HkTextarea } from "./components/HkTextarea";
+export { default as HkFileField } from "./components/HkFileField";
+export { default as HkFileBrowserDialog } from "./components/HkFileBrowserDialog";
+export { default as HkFilePickerField } from "./components/HkFilePickerField";
+export { default as HkToast } from "./components/HkToast";
+export { default as HkTooltip } from "./components/HkTooltip";
+export { default as HkTree } from "./components/HkTree";
+export { default as HkWindowedItem } from "./components/HkWindowedItem";
+export { default as HkWaterfall } from "./components/HkWaterfall";
+export { default as HkBlankCanvas } from "./components/HkBlankCanvas";
+export { default as HkKanban } from "./components/HkKanban";
+export { default as HkNodeCanvas } from "./components/HkNodeCanvas";
+export { default as HkDateTimePicker } from "./components/HkDateTimePicker";
+export { default as HkDatePicker } from "./components/HkDatePicker";
+export { default as HkTimeline } from "./components/HkTimeline";
+export { default as HkTitleBar } from "./components/HkTitleBar";
+export { default as HkStepFlow } from "./components/HkStepFlow";
+export { default as HkScrollPin } from "./components/HkScrollPin";
+export { default as HkMediaPlayer } from "./components/HkMediaPlayer";
+export { default as HkMediaControlBar } from "./components/HkMediaControlBar";
+export { default as HkMediaSlider } from "./components/HkMediaSlider";
+export { default as HkMediaVisualizer } from "./components/HkMediaVisualizer";
+export { default as HkImageViewer } from "./components/HkImageViewer";
+export { default as HkZoomToolbar } from "./components/HkZoomToolbar";
+export { default as HkMinimap } from "./components/HkMinimap";
+export { default as HkTrendChart } from "./components/HkTrendChart";
+export { default as HkErrorBoundary } from "./components/HkErrorBoundary";
+export { default as HkDraggableList } from "./components/HkDraggableList";
+export { default as HkDraggableGrid } from "./components/HkDraggableGrid";
+export { default as HkSelectionGrid } from "./components/HkSelectionGrid";
+export { default as HkSelectionWaterfall } from "./components/HkSelectionWaterfall";
+export { default as HkLogo } from "./components/HkLogo";
+export { default as HkAuthMethodList } from "./components/HkAuthMethodList";
+export { default as HkAuthSubmitButton } from "./components/HkAuthSubmitButton";
+export { type HkDockBarAnchor as HkDockBarAnchor } from "./components/HkDockBar";
+export { type HkDockBarSurface as HkDockBarSurface } from "./components/HkDockBar";
+export { HkOtpInput as HkOtpInput } from "./components/HkOtpInput";
+export { HkLocalizedInput as HkLocalizedInput } from "./components/HkLocalizedInput";
+export { HkTagInput as HkTagInput } from "./components/HkTagInput";
+export { HkErrorLanding as HkErrorLanding } from "./components/HkErrorLanding";
+export { HkErrorReportingOverlay as HkErrorReportingOverlay } from "./errorReporting";
+export { HkAdminShell as HkAdminShell } from "./components/HkAdminShell";
+export { HkAdminHeader as HkAdminHeader } from "./components/HkAdminHeader";
+export { HkNavSidebar as HkNavSidebar } from "./components/HkNavSidebar";
+export { HkThemeToggle as HkThemeToggle } from "./components/HkThemeToggle";
+export { HkAuthCard as HkAuthCard } from "./components/HkAuthCard";
+export { HkSignInCard as HkSignInCard } from "./components/HkSignInCard";
+export { HkMfaVerifyCard as HkMfaVerifyCard } from "./components/HkMfaVerifyCard";
+export { type HkMfaFactor as HkMfaFactor } from "./components/HkMfaVerifyCard";
+export { HkLocalePicker as HkLocalePicker } from "./components/HkLocalePicker";
+export { HkAdminTablePage as HkAdminTablePage } from "./components/HkAdminTablePage";
+export { HkPageHeader as HkPageHeader } from "./components/HkPageHeader";
+export { HkStatCard as HkStatCard } from "./components/HkStatCard";
+export { HkStatusPill as HkStatusPill } from "./components/HkStatusPill";
+export { HkShareBar as HkShareBar } from "./components/HkShareBar";
+export { HkSecretRevealModal as HkSecretRevealModal } from "./components/HkSecretRevealModal";
+export { HkCaptchaWidget as HkCaptchaWidget } from "./components/HkCaptchaWidget";
+export { HkCaptchaModal as HkCaptchaModal } from "./components/HkCaptchaModal";
+export { HkProtocolModal as HkProtocolModal } from "./components/HkProtocolModal";
+export { HkAboutModal as HkAboutModal } from "./components/HkAboutModal";
+export { HkLogWindow as HkLogWindow } from "./components/HkLogWindow";
+export { HkSettingsBody as HkSettingsBody } from "./components/HkSettingsDialog";
+export { HkSettingsDialog as HkSettingsDialog } from "./components/HkSettingsDialog";
+export { HkSettingsGroup as HkSettingsGroup } from "./components/HkSettingsDialog";
+export { HkSettingsSub as HkSettingsSub } from "./components/HkSettingsDialog";
+export { HkSettingsHint as HkSettingsHint } from "./components/HkSettingsDialog";
+export { HkCookieConsent as HkCookieConsent } from "./components/HkCookieConsent";
+export { HkAttachmentModal as HkAttachmentModal } from "./components/HkAttachmentModal";
+export { HkStatusBar as HkStatusBar } from "./components/HkStatusBar";
+export { HkCountdownDigit as HkCountdownDigit } from "./components/HkCountdownDigit";
+export { HkConnectionStatus as HkConnectionStatus } from "./components/HkConnectionStatus";
+export { HkRichInput as HkRichInput } from "./components/HkRichInput";
+export { HkVoiceInputPopup as HkVoiceInputPopup } from "./components/HkVoiceInputPopup";
+export { HkToolBlock as HkToolBlock } from "./components/HkToolBlock";
+export { HkJsonTree as HkJsonTree } from "./components/HkJsonTree";
+export { HkTokenUsageBadge as HkTokenUsageBadge } from "./components/HkTokenUsageBadge";
+export { HkTokenUsagePanel as HkTokenUsagePanel } from "./components/HkTokenUsagePanel";
+export { HkModelTag as HkModelTag } from "./components/HkModelTag";

package/src/theme/index.ts

@@ -32,7 +32,7 @@ export type { GeoLocation, GeoLocationProvider } from "./useSolarTime";
 export { refreshThemeClock, stopThemeClock } from "./useTheme";
 export {
   startLuminanceSampler, stopLuminanceSampler, sampleLuminanceNow, invalidateLuminanceCache,
-  registerWallpaperSurfaceSources, resolveWallpaperSurfaceElement, LEGACY_WALLPAPER_SURFACE_IDS,
+  registerWallpaperSurfaceSources, resolveWallpaperSurfaceElement,
   retainLuminanceSampler, releaseLuminanceSampler, luminanceSamplerRefCount,
 } from "./useBackgroundLuminance";
 export type { WallpaperSurfaceKind, WallpaperSurfaceSources } from "./useBackgroundLuminance";

package/src/theme/useBackgroundLuminance.test.ts

@@ -1,7 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
-  LEGACY_WALLPAPER_SURFACE_IDS,
   luminanceSamplerRefCount,
   registerWallpaperSurfaceSources,
   releaseLuminanceSampler,
@@ -23,15 +22,21 @@ import {
  * derived from the body background instead of the wallpaper.
  *
  * Three facts are pinned here:
- *   1. a REGISTERED surface is what gets sampled, even when its element id
- *      is nothing like chest's (the assertion that would have failed for
- *      every consumer but chest);
- *   2. the legacy ids still resolve when nothing is registered (chest keeps
- *      working until its own migration PR);
+ *   1. a REGISTERED surface is what gets sampled, whatever its element id
+ *      is (the assertion that would have failed for every consumer but
+ *      chest);
+ *   2. registration is the WHOLE contract: the retired ids are inert, and
+ *      "nothing registered" resolves to null so the sampler takes its
+ *      documented body-background path instead of reading a stranger's
+ *      element;
  *   3. the shared loop is reference-counted, so an unmounting backdrop
  *      releases only its own claim.
  */
 
+/** The ids the sampler used to look up before the registry existed. Still
+ *  spelled out here, because the point of case 2 is that they mean nothing. */
+const RETIRED_IDS = { canvas: "s-wallpaper-canvas", video: "s-wallpaper-video" } as const;
+
 /** A WebGL2 context stub just real enough for the PBO round trip. */
 function makeGl(pixel: [number, number, number, number]) {
   return {
@@ -105,20 +110,21 @@ afterEach(() => {
 
 describe("wallpaper surface registry", () => {
   it("proves the detector can tell two canvases apart (positive control)", () => {
-    makeCanvas(LEGACY_WALLPAPER_SURFACE_IDS.canvas, makeGl(BRIGHT));
+    makeCanvas("hk-wallpaper-canvas-decoy", makeGl(BRIGHT));
     const mine = makeCanvas("hk-wallpaper-canvas-instance-1", makeGl(DARK));
     stubCanvasContexts();
 
-    expect(resolveWallpaperSurfaceElement("canvas")).toBe(
-      document.getElementById(LEGACY_WALLPAPER_SURFACE_IDS.canvas),
-    );
+    expect(
+      resolveWallpaperSurfaceElement("canvas"),
+      "an unregistered element is not the sampler's source",
+    ).toBeNull();
 
     disposers.push(registerWallpaperSurfaceSources({ canvas: () => mine }));
     expect(resolveWallpaperSurfaceElement("canvas")).toBe(mine);
   });
 
-  it("samples the REGISTERED surface, not chest's fixed id", async () => {
-    const legacy = makeCanvas(LEGACY_WALLPAPER_SURFACE_IDS.canvas, makeGl(BRIGHT));
+  it("samples the REGISTERED surface, not the retired ids", async () => {
+    const retired = makeCanvas(RETIRED_IDS.canvas, makeGl(BRIGHT));
     // A different id AND a different class: nothing about this element
     // matches what the sampler used to look for.
     const registered = makeCanvas("hk-wallpaper-canvas-7f3a", makeGl(DARK));
@@ -133,31 +139,49 @@ describe("wallpaper surface registry", () => {
     await frame();
 
     expect(probed, "only the registered element is probed").toContain(registered);
-    expect(probed, "chest's element is never touched").not.toContain(legacy);
+    expect(probed, "the retired id is never touched").not.toContain(retired);
     // A DARK surface ⇒ white floating text (the registered element's pixels).
     expect(luminanceVar()).toBe("255, 255, 255");
   });
 
-  it("still resolves the legacy ids when nothing is registered", () => {
-    const legacyCanvas = makeCanvas(LEGACY_WALLPAPER_SURFACE_IDS.canvas, makeGl(BRIGHT));
-    const legacyVideo = document.createElement("video");
-    legacyVideo.id = LEGACY_WALLPAPER_SURFACE_IDS.video;
-    document.body.appendChild(legacyVideo);
+  it("does not resolve the retired ids when nothing is registered", () => {
+    const retiredCanvas = makeCanvas(RETIRED_IDS.canvas, makeGl(BRIGHT));
+    const retiredVideo = document.createElement("video");
+    retiredVideo.id = RETIRED_IDS.video;
+    document.body.appendChild(retiredVideo);
     stubCanvasContexts();
 
-    expect(resolveWallpaperSurfaceElement("canvas")).toBe(legacyCanvas);
-    expect(resolveWallpaperSurfaceElement("video")).toBe(legacyVideo);
+    expect(document.getElementById(RETIRED_IDS.canvas)).toBe(retiredCanvas);
+    expect(resolveWallpaperSurfaceElement("canvas")).toBeNull();
+    expect(resolveWallpaperSurfaceElement("video")).toBeNull();
   });
 
   it("stops using a surface as soon as its owner disposes the registration", () => {
-    const legacy = makeCanvas(LEGACY_WALLPAPER_SURFACE_IDS.canvas, null);
+    const retired = makeCanvas(RETIRED_IDS.canvas, null);
     const registered = makeCanvas("hk-wallpaper-canvas-transient", null);
     stubCanvasContexts();
 
     const dispose = registerWallpaperSurfaceSources({ canvas: () => registered });
     expect(resolveWallpaperSurfaceElement("canvas")).toBe(registered);
     dispose();
-    expect(resolveWallpaperSurfaceElement("canvas")).toBe(legacy);
+    expect(document.getElementById(RETIRED_IDS.canvas)).toBe(retired);
+    expect(resolveWallpaperSurfaceElement("canvas")).toBeNull();
+  });
+
+  it("keeps the other owner's surface when one registration disposes", () => {
+    const mine = makeCanvas("hk-wallpaper-canvas-my-owner", null);
+    const other = makeCanvas("hk-wallpaper-canvas-other-owner", null);
+    stubCanvasContexts();
+
+    const disposeMine = registerWallpaperSurfaceSources({ canvas: () => mine });
+    disposers.push(registerWallpaperSurfaceSources({ canvas: () => other }));
+    expect(resolveWallpaperSurfaceElement("canvas")).toBe(other);
+
+    disposeMine();
+    // Disposal is per registration, not a sweep: the survivor must keep
+    // answering, or the second backdrop (chest mounts one per layout) loses
+    // its contrast sampling the moment the first unmounts.
+    expect(resolveWallpaperSurfaceElement("canvas")).toBe(other);
   });
 
   it("prefers the newest registration that resolves", () => {

package/src/theme/useBackgroundLuminance.ts

@@ -12,14 +12,18 @@ const CVAR_BADGE = "--float-badge-color";
 // null, `sampleFrame` falls through to the body background, and text
 // contrast is computed from the wrong surface with no error anywhere.
 //
-// The contract is now explicit in both directions:
-//   - whoever owns a wallpaper surface REGISTERS it (as a getter, because a
-//     renderer may re-create the element — hikari's HkWallpaperBackdrop
-//     re-renders its layers from state, so a captured element reference
-//     would go stale on the first wallpaper switch),
-//   - the legacy ids stay as the FALLBACK, so a host that has not migrated
-//     (chest, until its own PR) keeps sampling exactly what it samples
-//     today.
+// The contract is explicit, in one direction only: whoever owns a wallpaper
+// surface REGISTERS it, as a getter, because a renderer may re-create the
+// element — hikari's HkWallpaperBackdrop re-renders its layers from state,
+// so a captured element reference would go stale on the first wallpaper
+// switch.
+//
+// The id fallback kept smaller hosts working while they migrated, and both
+// had landed by 2026-09-24 (chest #1123, erp.celestia.world #123): every
+// surface owner now registers, none of them renders those ids, and a
+// fallback that matches nothing is exactly the silent wrong-surface read it
+// was meant to avoid. So it is gone, and "no registration" means null —
+// `sampleFrame` then takes its documented body-background path.
 
 /** The two wallpaper surfaces the sampler can read. */
 export type WallpaperSurfaceKind = "canvas" | "video";
@@ -32,15 +36,6 @@ export interface WallpaperSurfaceSources {
   video?: () => HTMLVideoElement | null | undefined;
 }
 
-/**
- * Element ids the sampler assumed before the registry existed. Read-only
- * fallbacks for a host that has not registered a source; never written.
- */
-export const LEGACY_WALLPAPER_SURFACE_IDS: Readonly<Record<WallpaperSurfaceKind, string>> = {
-  canvas: "s-wallpaper-canvas",
-  video: "s-wallpaper-video",
-};
-
 const surfaceSources = new Map<symbol, WallpaperSurfaceSources>();
 
 /**
@@ -61,8 +56,9 @@ export function registerWallpaperSurfaceSources(sources: WallpaperSurfaceSources
   };
 }
 
-/** Resolve the live element for `kind`: newest registered source that
- *  resolves, else the legacy id, else null. */
+/** Resolve the live element for `kind`: the newest registered source that
+ *  resolves, else null. Registration is the whole contract — there is no id
+ *  to fall back to. */
 export function resolveWallpaperSurfaceElement(kind: WallpaperSurfaceKind): HTMLElement | null {
   const tokens = [...surfaceSources.keys()];
   for (let i = tokens.length - 1; i >= 0; i -= 1) {
@@ -70,8 +66,7 @@ export function resolveWallpaperSurfaceElement(kind: WallpaperSurfaceKind): HTML
     const el = source?.[kind]?.();
     if (el) return el;
   }
-  if (typeof document === "undefined") return null;
-  return document.getElementById(LEGACY_WALLPAPER_SURFACE_IDS[kind]);
+  return null;
 }
 
 let handle: AnimationHandle | null = null;