@celestia-island/hikari 0.55.71 → 0.55.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.71",
+  "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/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;