@celestia-island/hikari 0.4.4 → 0.30.0

package/src/theme/useSolarTime.ts

@@ -66,36 +66,111 @@ export function getTimePeriod(
 
 export const DEFAULT_GEO_LOCATION = { lat: 31.23, lng: 121.47 };
 
+/** Resolved geographic coordinates in degrees. */
+export interface GeoLocation {
+  lat: number;
+  lng: number;
+}
+
+/**
+ * Host-supplied geolocation source. Native shells (Tauri 2's geolocation
+ * plugin, Electron IPC, a saved user preference, …) register one with
+ * `setGeolocationProvider` so the theme clock uses the device's real fix
+ * instead of hikari's web cascade. Return the coordinates, or return
+ * null / throw to fall through to the standard cascade (already-granted
+ * browser geolocation → IP lookup → timezone estimate).
+ */
+export type GeoLocationProvider = () => Promise<GeoLocation | null>;
+
+let geoProvider: GeoLocationProvider | null = null;
+
+/** One successful resolution per page is shared by every consumer (theme
+ *  clock, theme toggle readout, wallpaper clock). Reset by
+ *  `setGeolocationProvider` so a late registration is honored on the next
+ *  call; the timezone estimate is never memoized, so a transient offline
+ *  boot can heal on the next `getGeolocation` / `refreshThemeClock`. */
+let geoMemo: Promise<GeoLocation> | null = null;
+
+export function setGeolocationProvider(provider: GeoLocationProvider | null): void {
+  geoProvider = provider;
+  geoMemo = null;
+}
+
 const GEO_API_URL = "https://ipapi.co/json/";
 const GEO_API_TIMEOUT_MS = 4000;
 
-function timezoneFallback(): { lat: number; lng: number } {
+/** Synchronous coarse estimate: default latitude + the timezone-offset
+ *  longitude. No fetch, no permission — the first-paint guess. */
+export function timezoneFallback(): GeoLocation {
   const offsetMin = -new Date().getTimezoneOffset();
   const lng = offsetMin / 4;
   return { lat: DEFAULT_GEO_LOCATION.lat, lng };
 }
 
-export function getGeolocation(): Promise<{ lat: number; lng: number }> {
+async function browserGeolocation(): Promise<GeoLocation> {
+  // Standard web geolocation — but ONLY when the site already holds the
+  // permission: a theme must never be the thing that pops the browser's
+  // location prompt. Prompt/denied/unavailable all fall through to the IP
+  // lookup.
+  if (typeof navigator === "undefined" || !navigator.geolocation) {
+    throw new Error("navigator.geolocation unavailable");
+  }
+  const perm = await navigator.permissions?.query({ name: "geolocation" as PermissionName });
+  if (!perm || perm.state !== "granted") {
+    throw new Error("geolocation permission not granted");
+  }
+  return new Promise<GeoLocation>((resolve, reject) => {
+    navigator.geolocation.getCurrentPosition(
+      (pos) => resolve({ lat: pos.coords.latitude, lng: pos.coords.longitude }),
+      (err) => reject(err),
+      { timeout: GEO_API_TIMEOUT_MS, maximumAge: 6 * 60 * 60 * 1000 },
+    );
+  });
+}
+
+async function ipGeolocation(): Promise<GeoLocation> {
   const controller = new AbortController();
   const timer = scheduleCronAfter(() => controller.abort(), GEO_API_TIMEOUT_MS);
-  return fetch(GEO_API_URL, { signal: controller.signal, cache: "no-store" })
+  const d = await fetch(GEO_API_URL, { signal: controller.signal, cache: "no-store" })
     .then((r) => (r.ok ? r.json() : null))
-    .then(
-      (d: { latitude?: number; longitude?: number } | null) => {
-        timer.disconnect();
-        if (
-          d &&
-          typeof d.latitude === "number" &&
-          typeof d.longitude === "number" &&
-          (Math.abs(d.latitude) > 0.01 || Math.abs(d.longitude) > 0.01)
-        ) {
-          return { lat: d.latitude, lng: d.longitude };
+    .finally(() => timer.disconnect()) as { latitude?: number; longitude?: number } | null;
+  if (
+    d &&
+    typeof d.latitude === "number" &&
+    typeof d.longitude === "number" &&
+    (Math.abs(d.latitude) > 0.01 || Math.abs(d.longitude) > 0.01)
+  ) {
+    return { lat: d.latitude, lng: d.longitude };
+  }
+  throw new Error("ip geolocation unavailable");
+}
+
+export function getGeolocation(): Promise<GeoLocation> {
+  geoMemo ??= (async () => {
+    if (geoProvider) {
+      try {
+        const provided = await geoProvider();
+        if (provided && Number.isFinite(provided.lat) && Number.isFinite(provided.lng)) {
+          return { lat: provided.lat, lng: provided.lng };
         }
-        return timezoneFallback();
-      },
-      () => {
-        timer.disconnect();
-        return timezoneFallback();
-      },
-    );
+      } catch {
+        // Provider failed — fall through to the standard cascade.
+      }
+    }
+    try {
+      return await browserGeolocation();
+    } catch {
+      // No API / not granted / denied — never prompt for a theme.
+    }
+    try {
+      return await ipGeolocation();
+    } catch {
+      // Offline or the lookup service is down.
+    }
+    // Don't pin the estimate for the whole session — drop the memo so the
+    // next call retries the cascade.
+    geoMemo = null;
+    return timezoneFallback();
+  })();
+  return geoMemo;
 }

package/src/theme/useTheme.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// The theme engine keeps singleton state (mode/theme refs + clock flag), so
+// every test gets a fresh module instance via vi.resetModules + dynamic import.
+type ThemeModule = typeof import("./useTheme");
+type SolarModule = typeof import("./useSolarTime");
+
+describe("useTheme theme clock", () => {
+  let theme: ThemeModule;
+  let solar: SolarModule;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.unstubAllGlobals();
+    localStorage.clear();
+    document.documentElement.style.cssText = "";
+    document.documentElement.removeAttribute("data-theme");
+    document.documentElement.removeAttribute("data-mode");
+    // Nothing here may touch the real network.
+    vi.stubGlobal("fetch", vi.fn(async () => {
+      throw new Error("offline");
+    }));
+    solar = await import("./useSolarTime");
+    theme = await import("./useTheme");
+  });
+
+  afterEach(() => {
+    theme.stopThemeClock();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("initTheme starts the clock; the geo fix feeds geo/period on useTheme()", async () => {
+    solar.setGeolocationProvider(async () => ({ lat: 40.71, lng: -74.01 }));
+    theme.initTheme();
+
+    const th = theme.useTheme();
+    // Synchronous first paint: the timezone estimate, not the default
+    // Shanghai constant.
+    expect(th.geo.value.lng).toBeCloseTo(-new Date().getTimezoneOffset() / 4);
+
+    await vi.waitFor(() => {
+      expect(th.geo.value).toEqual({ lat: 40.71, lng: -74.01 });
+    });
+    expect(["day", "dusk", "night"]).toContain(th.period.value);
+  });
+
+  it("refreshThemeClock honors a provider registered after initTheme", async () => {
+    theme.initTheme();
+    // No provider yet → the cascade bottoms out at the timezone estimate,
+    // which must NOT be pinned.
+    const first = await theme.refreshThemeClock();
+    expect(first.lng).toBeCloseTo(-new Date().getTimezoneOffset() / 4);
+
+    solar.setGeolocationProvider(async () => ({ lat: -33.87, lng: 151.21 }));
+    const second = await theme.refreshThemeClock();
+    expect(second).toEqual({ lat: -33.87, lng: 151.21 });
+    expect(theme.useTheme().geo.value).toEqual({ lat: -33.87, lng: 151.21 });
+  });
+
+  it("stopThemeClock allows initTheme to restart the clock", async () => {
+    solar.setGeolocationProvider(async () => ({ lat: 1, lng: 2 }));
+    theme.initTheme();
+    await vi.waitFor(() => {
+      expect(theme.useTheme().geo.value).toEqual({ lat: 1, lng: 2 });
+    });
+    theme.stopThemeClock();
+    // Restarting the clock keeps the engine consistent (idempotent lifecycle).
+    theme.initTheme();
+    expect(theme.useTheme().geo.value).toEqual({ lat: 1, lng: 2 });
+  });
+});

package/src/theme/useTheme.ts

@@ -1,26 +1,141 @@
 import { computed, ref, watch } from "vue";
 
 import { scheduleCronAfter, type CronHandle } from "../runtime/cronBus";
+import { scheduleInterval, type IntervalHandle } from "../runtime/intervalBus";
 import { addCustomTheme as addCustomThemeToStorage, loadCustomThemes, removeCustomTheme as removeCustomThemeFromStorage, themePresets, tokensToCSSVars, type CustomThemePreset, type ThemeId, type ThemeMode, type ThemePreset } from "./presets";
+import { groupTokensToCSSVars, resolveGroupTokens, setTokenGroupsReapply } from "./tokenGroups";
 import { invalidateLuminanceCache } from "./useBackgroundLuminance";
-import { getTimePeriod, DEFAULT_GEO_LOCATION, type TimePeriod } from "./useSolarTime";
+import { getGeolocation, getTimePeriod, timezoneFallback, type GeoLocation, type TimePeriod } from "./useSolarTime";
 
 const DEFAULT_THEME = "synthwave84";
 const STORAGE_THEME_KEY = "hikari-theme";
-const STORAGE_MODE_KEY = "hikari-theme-mode";
+export const THEME_MODE_STORAGE_KEY = "hikari-theme-mode";
+const STORAGE_MODE_KEY = THEME_MODE_STORAGE_KEY;
+
+// Page-declared brand themes (optional): a site may declare
+// window.__celestiaThemes (extra theme ids) and window.__celestiaDefaultTheme
+// in its index.html before this module loads. Honor them when resolving the
+// stored theme id so a brand id like "endfield" is not dropped as unknown.
+// Both helpers are no-ops when the globals are absent, keeping every other
+// consumer's behavior unchanged.
+interface PageDeclaredThemeGlobals {
+  __celestiaThemes?: Record<string, unknown>;
+  __celestiaDefaultTheme?: string;
+}
+
+function pageDeclaredThemes(): Record<string, unknown> {
+  if (typeof window === "undefined") return {};
+  return (window as Window & PageDeclaredThemeGlobals).__celestiaThemes ?? {};
+}
+
+function pageDeclaredDefaultTheme(): string | null {
+  if (typeof window === "undefined") return null;
+  const declared = (window as Window & PageDeclaredThemeGlobals).__celestiaDefaultTheme;
+  return typeof declared === "string" ? declared : null;
+}
+
+function resolveDefaultTheme(): ThemeId {
+  const declared = pageDeclaredDefaultTheme();
+  if (
+    declared &&
+    (declared in themePresets || declared in pageDeclaredThemes())
+  ) {
+    return declared as ThemeId;
+  }
+  return DEFAULT_THEME;
+}
 
-const currentTheme = ref<ThemeId>(
-  localStorage.getItem(STORAGE_THEME_KEY) || DEFAULT_THEME,
-);
 const currentMode = ref<ThemeMode>(
   (localStorage.getItem(STORAGE_MODE_KEY) as ThemeMode) || "system",
 );
 const customThemes = ref<CustomThemePreset[]>(loadCustomThemes());
 
+function storedThemeId(): ThemeId {
+  const stored = localStorage.getItem(STORAGE_THEME_KEY);
+  if (stored) {
+    const known = new Set<string>([
+      ...Object.keys(themePresets),
+      ...Object.keys(pageDeclaredThemes()),
+      ...customThemes.value.map((c: CustomThemePreset) => c.id),
+    ]);
+    if (known.has(stored)) return stored as ThemeId;
+    // Stale/invalid theme id (e.g. written by an older build): drop it so
+    // applyTheme() never silently bails and leaves the page unthemed.
+    localStorage.removeItem(STORAGE_THEME_KEY);
+  }
+  return resolveDefaultTheme();
+}
+
+const currentTheme = ref<ThemeId>(storedThemeId());
+
 const currentPeriod = ref<TimePeriod>(
-  getTimePeriod(DEFAULT_GEO_LOCATION.lat, DEFAULT_GEO_LOCATION.lng),
+  // First paint uses the synchronous timezone-offset estimate; the theme
+  // clock below refines it with a real geolocation fix once that lands.
+  getTimePeriod(timezoneFallback().lat, timezoneFallback().lng),
 );
 
+/**
+ * The theme clock. `system` mode resolves day/night from the sun, so it
+ * needs (a) a real geolocation fix and (b) re-evaluation as time passes —
+ * previously the period was computed once at module init from
+ * DEFAULT_GEO_LOCATION and never refreshed, pinning auto mode to Shanghai's
+ * daylight at load time.
+ */
+const themeGeo = ref<GeoLocation>(timezoneFallback());
+
+/** How often the solar period is recomputed from the cached coordinates
+ *  (dawn/dusk flips while the page stays open). Visibility-aware: the
+ *  interval bus pauses while hidden and catches up once on return. */
+const THEME_CLOCK_TICK_MS = 5 * 60 * 1000;
+
+function updatePeriod() {
+  currentPeriod.value = getTimePeriod(themeGeo.value.lat, themeGeo.value.lng);
+}
+
+let clockStarted = false;
+let clockInterval: IntervalHandle | null = null;
+
+function startThemeClock() {
+  if (clockStarted) return;
+  clockStarted = true;
+  // Fire-and-forget: a failed fix keeps the timezone estimate silently.
+  void getGeolocation()
+    .then((geo) => {
+      themeGeo.value = geo;
+      updatePeriod();
+      if (currentMode.value === "system") applyTheme();
+    })
+    .catch(() => {});
+  clockInterval = scheduleInterval(() => {
+    const before = currentPeriod.value;
+    updatePeriod();
+    // Re-apply only on an actual day↔night flip while in system mode —
+    // manual modes ignore the period entirely.
+    if (currentMode.value === "system" && currentPeriod.value !== before) {
+      applyTheme();
+    }
+  }, THEME_CLOCK_TICK_MS);
+}
+
+/** Re-run the geolocation resolution (and re-apply in system mode). For
+ *  hosts that registered a geolocation provider after initTheme(), or that
+ *  want a manual refresh (network reconnect, wake-from-sleep). */
+export function refreshThemeClock(): Promise<GeoLocation> {
+  return getGeolocation().then((geo) => {
+    themeGeo.value = geo;
+    updatePeriod();
+    if (currentMode.value === "system") applyTheme();
+    return geo;
+  });
+}
+
+/** Stop the theme clock. Host teardown / tests; initTheme() restarts it. */
+export function stopThemeClock() {
+  clockInterval?.disconnect();
+  clockInterval = null;
+  clockStarted = false;
+}
+
 let initialized = false;
 
 function resolveEffectiveMode(mode: ThemeMode): "dark" | "light" {
@@ -43,7 +158,13 @@ function applyTheme() {
 
   const effectiveMode = resolveEffectiveMode(currentMode.value);
   const tokens = effectiveMode === "dark" ? preset.dark : preset.light;
-  const vars = tokensToCSSVars(tokens);
+  // Extension token groups always emit their cssvars: preset/custom-theme
+  // overrides win, registry defaults are the final fallback, so consumers
+  // can rely on `--<group>-<slot>` existing once the group is registered.
+  const groupVars = groupTokensToCSSVars(
+    resolveGroupTokens(effectiveMode, preset.groups?.[effectiveMode]),
+  );
+  const vars = tokensToCSSVars(tokens, groupVars);
 
   invalidateLuminanceCache();
 
@@ -61,6 +182,14 @@ function applyTheme() {
   }, THEME_TRANSITION_DURATION);
 }
 
+// Late token-group registrations re-apply the current theme so their
+// cssvars land immediately (microtask-coalesced) instead of waiting for
+// the next theme/mode switch. The registry lives in tokenGroups.ts and
+// must not import this module (that would be a cycle), so it calls back
+// through this injected hook. Hikari wires it once on module load;
+// applications never call setTokenGroupsReapply themselves.
+setTokenGroupsReapply(() => applyTheme());
+
 function getAllThemePresets(): Record<string, ThemePreset> {
   const result: Record<string, ThemePreset> = { ...themePresets };
   for (const ct of customThemes.value) {
@@ -77,6 +206,7 @@ export function initTheme() {
     currentMode.value = storedMode;
   }
   applyTheme();
+  startThemeClock();
 }
 
 export function useTheme() {
@@ -88,7 +218,7 @@ export function useTheme() {
       name: themePresets[id as keyof typeof themePresets].name,
       isCustom: false,
     }));
-    const custom = customThemes.value.map((ct) => ({
+    const custom = customThemes.value.map((ct: CustomThemePreset) => ({
       id: ct.id,
       name: ct.name,
       isCustom: true,
@@ -121,7 +251,7 @@ export function useTheme() {
     removeCustomThemeFromStorage(id);
     customThemes.value = loadCustomThemes();
     if (currentTheme.value === id) {
-      setTheme(DEFAULT_THEME);
+      setTheme(resolveDefaultTheme());
     }
   }
 
@@ -129,6 +259,11 @@ export function useTheme() {
     currentTheme,
     currentMode,
     effectiveMode,
+    /** The theme clock's resolved coordinates (timezone estimate until a
+     *  real fix lands). Read-only; refreshThemeClock() updates it. */
+    geo: computed(() => themeGeo.value),
+    /** The current solar period driving system mode. */
+    period: computed(() => currentPeriod.value),
     setTheme,
     setMode,
     toggleMode,

package/src/tokens.scss

@@ -23,4 +23,114 @@
   --border-input: rgb(var(--color-border, 100 100 100) / 15%);
   --border-faint: rgb(var(--color-border, 100 100 100) / 10%);
   --border-subtle: rgb(var(--color-border, 100 100 100) / 12%);
+
+  /* Icon-button state bridge — HkIconButtonVars references this vocabulary
+     but nothing ever defined it, so every var() without an in-file fallback
+     was invalid at computed-value time: non-ghost variants had no active
+     background, focus rings and glow vanished, and one missing item even
+     invalidated the whole transition shorthand (all icon buttons lost their
+     hover/press animation). Defined once here as live expressions over the
+     theme triplets so they track whichever palette is active; the -dark
+     variants are the pressed-step of their base slot. */
+  --hi-icon-color: rgb(var(--color-text, 30 30 30));
+  --hi-icon-size-xs: 0.75rem;
+  --hi-icon-size-sm: 1rem;
+  --hi-icon-size-md: 1.25rem;
+  --hi-icon-size-lg: 1.5rem;
+  --hi-duration-instant: var(--duration-instant, 0.1s);
+  --hi-border-color-focus: rgb(var(--color-primary, 122 162 247));
+  --hi-glow-color: transparent;
+  --hi-bg-surface-dark: rgb(var(--color-muted, 108 108 108) / 12%);
+  --hi-color-primary-dark: color-mix(in srgb, rgb(var(--color-primary, 122 162 247)) 82%, #000);
+  --hi-color-secondary-dark: color-mix(in srgb, rgb(var(--color-secondary, 81 154 115)) 82%, #000);
+  --hi-color-danger-dark: color-mix(in srgb, rgb(var(--color-error, 200 50 50)) 82%, #000);
+  --hi-color-success-dark: color-mix(in srgb, rgb(var(--color-success, 0 150 0)) 82%, #000);
+  --hi-color-text-on-secondary: rgb(var(--color-on-solid, 255 255 255));
+  --hi-color-text-on-danger: rgb(var(--color-on-solid, 255 255 255));
+  --hi-color-text-on-success: rgb(var(--color-on-solid, 255 255 255));
+}
+
+/* Static default light theme — renders correctly even without initTheme().
+   initTheme() overrides these at runtime via inline styles on
+   documentElement, which beat stylesheet :root declarations. */
+:root {
+  --color-primary: 122 162 247;
+  --color-on-primary: 255 255 255;
+  --color-on-solid: 255 255 255;
+  --color-on-solid-text: 255 255 255;
+  --color-on-solid-icon: 255 255 255;
+  --color-secondary: 81 154 115;
+  --color-accent: 247 181 0;
+  --color-text: 30 30 30;
+  --color-text-secondary: 102 102 102;
+  --color-text-tertiary: 140 140 140;
+  --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;
+  --color-success: 14 184 64;
+  --color-error: 247 118 142;
+  --color-warning: 238 214 119;
+  --color-info: 106 190 214;
+
+  --hi-color-primary: rgb(var(--color-primary));
+  --hi-color-secondary: rgb(var(--color-secondary));
+  --hi-color-surface: rgb(var(--color-surface));
+  --hi-color-background: rgb(var(--color-background));
+  --hi-color-border: rgb(var(--color-border));
+  --hi-color-text-primary: rgb(var(--color-text));
+  --hi-color-text-secondary: rgb(var(--color-text-secondary));
+  --hi-color-muted: rgb(var(--color-muted));
+  --hi-color-on-primary: rgb(var(--color-on-primary));
+  /* Deprecated in-tree: luminance-computed contrast, kept only for external
+     consumers. In-tree components use the on-solid slots instead. */
+  --hi-color-text-on-primary: rgb(var(--color-on-primary));
+  --hi-color-text-on-solid: rgb(var(--color-on-solid-text, 255 255 255));
+  --hi-color-icon-on-solid: rgb(var(--color-on-solid-icon, 255 255 255));
+  --hi-color-success: rgb(var(--color-success));
+  --hi-color-error: rgb(var(--color-error));
+  --hi-color-warning: rgb(var(--color-warning));
+  --hi-color-info: rgb(var(--color-info));
+
+  /* Design tokens consumed by hikari components. These used to live only in
+     plana-ui's token set; without them the background/backdrop declarations
+     of fields and surfaces resolve to nothing. Values align with plana-ui. */
+  --space-2: 0.125rem;
+  --space-4: 0.25rem;
+  --space-6: 0.375rem;
+  --space-8: 0.5rem;
+  --space-10: 0.625rem;
+  --space-12: 0.75rem;
+  --space-14: 0.875rem;
+  --space-16: 1rem;
+  --space-20: 1.25rem;
+  --space-24: 1.5rem;
+  --space-28: 1.75rem;
+  --space-32: 2rem;
+  --space-40: 2.5rem;
+  --text-2xs: 0.625rem;
+  --text-xs: 0.75rem;
+  --text-sm: 0.8125rem;
+  --text-base: 0.875rem;
+  --text-md: 1rem;
+  --text-lg: 1.125rem;
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --opacity-half: 0.92;
+  --blur-sm: 8px;
+  --blur-md: 16px;
+  --blur-lg: 24px;
+  --duration-fast: 0.15s;
+  --duration-short: 0.15s;
+  --duration-normal: 0.3s;
+  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
+  --ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
+  --s-footer-height: 3rem;
+  --z-header: 30;
+  --z-sidebar: 40;
+  /* Apple-style stack + CJK UI tail — keep in sync with packages/vue/src/theme/fontContext.ts */
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
+  --font-reading: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
 }

package/src/utils/base64.ts

@@ -0,0 +1,31 @@
+/** Encode a binary buffer as a base64 string. */
+export function bytesToBase64(bytes: ArrayBuffer | Uint8Array): string {
+  const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  const chunk = 0x8000;
+  for (let i = 0; i < buf.length; i += chunk) {
+    binary += String.fromCharCode(...buf.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+
+/** Decode a base64 string into raw bytes. */
+export function base64ToBytes(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** Read a Blob/File and return its base64 payload (no data: prefix). */
+export function blobToBase64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const result = String(reader.result ?? "");
+      resolve(result.includes(",") ? result.slice(result.indexOf(",") + 1) : result);
+    };
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(blob);
+  });
+}

package/src/utils/connectivity.ts

@@ -0,0 +1,51 @@
+/**
+ * Browser CORS reachability probe (upstreamed from shittim-chest).
+ *
+ * Distinguishes "host unreachable" from "not allowed by CORS": a
+ * credentialed fetch first; on failure a no-cors probe — if that also
+ * fails the origin is unreachable, otherwise the host responded but the
+ * CORS policy rejected the credentialed request.
+ */
+export type OriginProbe =
+  | { ok: true }
+  | { ok: false; reason: "unreachable" | "cors-blocked" };
+
+export async function probeOrigin(
+  url: string,
+  opts?: { fetchFn?: typeof fetch },
+): Promise<OriginProbe> {
+  const fetchFn = opts?.fetchFn ?? fetch;
+  try {
+    // A successful credentialed fetch means reachable + CORS-whitelisted,
+    // regardless of the HTTP status code (4xx/5xx still prove the origin).
+    await fetchFn(url, { credentials: "include", mode: "cors" });
+    return { ok: true };
+  } catch {
+    // no-cors probe: still reports success if the server is reachable,
+    // just without reading the response.
+    try {
+      await fetchFn(url, { mode: "no-cors" });
+      return { ok: false, reason: "cors-blocked" };
+    } catch {
+      return { ok: false, reason: "unreachable" };
+    }
+  }
+}
+
+/**
+ * Like `probeOrigin` but captures the response body when the credentialed
+ * fetch succeeds — for identity assertions (e.g. checking a product field)
+ * without re-implementing the probe ladder.
+ */
+export async function probeOriginWithBody(
+  url: string,
+  opts?: { fetchFn?: typeof fetch },
+): Promise<{ ok: boolean; body?: string }> {
+  const fetchFn = opts?.fetchFn ?? fetch;
+  try {
+    const resp = await fetchFn(url, { credentials: "include", mode: "cors" });
+    return { ok: true, body: await resp.text().catch(() => undefined) };
+  } catch {
+    return { ok: false };
+  }
+}