@celestia-island/hikari 0.46.0 → 0.47.0

package/package.json

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

package/src/composables/useConnectionProbe.ts

@@ -1,6 +1,7 @@
 import { onMounted, onUnmounted, ref, type Ref } from "vue";
 
 import { scheduleInterval, scheduleIntervalAfter, type IntervalHandle } from "../runtime/intervalBus";
+import { reportHkRuntime, type HkRuntimeHandle } from "../runtime/registry";
 
 /** Fetch-based connectivity probe — the hikari-local successor of the
  *  plana-ui probe. Polls `/api/health` (or a custom endpoint set via
@@ -28,6 +29,20 @@ const DEFAULT_RETRY_TOTAL = 3;
 
 let probeEndpoint: string | (() => string) = "";
 
+// Runtime-registry reporting (the "context of contexts"): the probe is a
+// per-component composable, so the MODULE is the hook — one registry
+// entry counting live probe instances, with the configured endpoint in
+// the read facet. Registration API unchanged.
+let liveProbes = 0;
+let probeRuntime: HkRuntimeHandle | null = null;
+function ensureProbeRuntime(): HkRuntimeHandle {
+  return (probeRuntime ??= reportHkRuntime("connectionProbe", {
+    kind: "hook",
+    description: "The fetch-based connectivity probe: per-component /api/health polling with retry and countdown.",
+    read: () => ({ liveProbes, endpoint: endpointUrl() }),
+  }));
+}
+
 /** Override the probed endpoint (defaults to same-origin `/api/health`). */
 export function setProbeEndpoint(endpoint: string | (() => string)): void {
   probeEndpoint = endpoint;
@@ -127,11 +142,15 @@ export function useConnectionProbe(): {
   }
 
   onMounted(() => {
+    liveProbes += 1;
+    ensureProbeRuntime().pulse({ liveProbes });
     void probeOnce();
     tickHandle = scheduleInterval(applyCountdown, 1000);
   });
 
   onUnmounted(() => {
+    liveProbes = Math.max(0, liveProbes - 1);
+    probeRuntime?.pulse({ liveProbes });
     pollHandle?.disconnect();
     pollHandle = null;
     tickHandle?.disconnect();

package/src/composables/useProgressDialog.ts

@@ -1,5 +1,7 @@
 import { reactive } from "vue";
 
+import { reportHkRuntime, type HkRuntimeHandle } from "../runtime/registry";
+
 export interface ProgressDialogState {
   open: boolean;
   title: string;
@@ -24,7 +26,27 @@ const state = reactive<ProgressDialogState>({
   max: 100,
 });
 
+// Runtime-registry reporting (the "context of contexts"). Lazy: the
+// progress-dialog context reports itself on first use and pulses on
+// open/close, so the live dialog tree is answerable from
+// readHkRuntime("progressDialog") without importing this module.
+let runtimeReport: HkRuntimeHandle | null = null;
+function ensureRuntimeReport(): HkRuntimeHandle {
+  return (runtimeReport ??= reportHkRuntime("progressDialog", {
+    kind: "context",
+    description: "The progress dialog context: the single global task-progress surface (title, log tail, value/max).",
+    read: () => ({
+      open: state.open,
+      title: state.title,
+      logLines: state.logs.length,
+      value: state.value,
+      max: state.max,
+    }),
+  }));
+}
+
 export function showProgressDialog(opts: { title: string }): ProgressDialogHandle {
+  ensureRuntimeReport().pulse({ open: true, title: opts.title });
   state.title = opts.title;
   state.logs = [];
   state.value = null;
@@ -43,10 +65,12 @@ export function showProgressDialog(opts: { title: string }): ProgressDialogHandl
     },
     close() {
       state.open = false;
+      runtimeReport?.pulse({ open: false });
     },
   };
 }
 
 export function useProgressDialog(): ProgressDialogState {
+  ensureRuntimeReport();
   return state;
 }

package/src/errorReporting/state.ts

@@ -1,5 +1,7 @@
 import { ref, type Ref } from "vue";
 
+import { reportHkRuntime, type HkRuntimeHandle } from "../runtime/registry";
+
 /** Where a reported error came from. */
 export type HkErrorSource = "vue" | "window" | "rejection" | "manual";
 
@@ -66,6 +68,10 @@ export function getErrorReportingOptions(): HkErrorReportingOptions {
 
 export function setErrorReportingOptions(options: HkErrorReportingOptions): void {
   activeOptions = options;
+  runtimeReport?.setMeta({
+    captureWindow: options.captureWindow !== false,
+    captureRejection: options.captureRejection !== false,
+  });
 }
 
 export function useErrorReportingState(): Ref<HkReportedError | null> {
@@ -86,6 +92,11 @@ export function reportError(err: unknown, source: HkErrorSource, info?: string):
 
   if (currentError.value !== null) return null;
 
+  // Accepted onto the landing (first-error-wins): later errors while the
+  // landing is up still log/fire onError above but do not count.
+  acceptedReports += 1;
+  runtimeReport?.pulse({ reports: acceptedReports });
+
   const normalized = normalizeError(err);
   const record: HkReportedError = {
     source,
@@ -102,3 +113,22 @@ export function reportError(err: unknown, source: HkErrorSource, info?: string):
 export function clearErrorReportingState(): void {
   currentError.value = null;
 }
+
+// Runtime-registry reporting (the "context of contexts"): the error
+// reporting module is a global singleton, so it reports itself at module
+// init and pulses on every accepted error. The read facet keeps the
+// current landing card observable (name/message/source only — never the
+// whole error object) from readHkRuntime("errorReporting").
+let acceptedReports = 0;
+const runtimeReport: HkRuntimeHandle = reportHkRuntime("errorReporting", {
+  kind: "plugin",
+  description: "The global error reporting landing: app.config.errorHandler + window/rejection hooks with the full-screen error card.",
+  meta: { captureWindow: activeOptions.captureWindow !== false, captureRejection: activeOptions.captureRejection !== false },
+  read: () => ({
+    reports: acceptedReports,
+    landingUp: currentError.value !== null,
+    current: currentError.value
+      ? { name: currentError.value.name, message: currentError.value.message, source: currentError.value.source }
+      : null,
+  }),
+});

package/src/i18n/context.ts

@@ -1,5 +1,7 @@
 import { reactive } from "vue";
 
+import { reportHkRuntime } from "../runtime/registry";
+
 type Messages = Record<string, string>;
 
 interface LocaleModule {
@@ -63,6 +65,7 @@ export async function setLocale(locale: string): Promise<void> {
     ...(mergedMessages["en"] ?? {}),
     ...(mergedMessages[locale] ?? {}),
   };
+  runtime.pulse({ locale });
 }
 
 export function mergeMessages(userMessages: Messages, locale?: string): void {
@@ -82,6 +85,7 @@ export function mergeMessages(userMessages: Messages, locale?: string): void {
     ...(mergedMessages["en"] ?? {}),
     ...(mergedMessages[state.locale] ?? {}),
   };
+  runtime.pulse({ locale: state.locale });
 }
 
 export function useI18n() {
@@ -96,3 +100,31 @@ export function useI18n() {
 
   return { t, locale: state.locale };
 }
+
+// Runtime-registry reporting (the "context of contexts"): the i18n
+// context is a module singleton, so it reports itself at module init and
+// pulses on every locale switch / message merge. The facets make the
+// locale tree reachable and steerable from anywhere via
+// readHkRuntime("i18n") / writeHkRuntime("i18n", …) without importing
+// this module.
+const runtime = reportHkRuntime("i18n", {
+  kind: "context",
+  description: "The i18n context: active locale, message tables and per-locale merged overrides.",
+  meta: { locale: state.locale },
+  read: () => ({
+    locale: state.locale,
+    keys: Object.keys(state.messages).length,
+    mergedLocales: Object.keys(mergedMessages),
+  }),
+  write: (op) => {
+    if (op.type === "setLocale" && typeof op.locale === "string") {
+      void setLocale(op.locale);
+      return;
+    }
+    if (op.type === "mergeMessages" && typeof op.messages === "object" && op.messages !== null) {
+      mergeMessages(op.messages as Messages, typeof op.locale === "string" ? op.locale : undefined);
+      return;
+    }
+    throw new Error(`unknown i18n write op "${op.type}"`);
+  },
+});

package/src/index.ts

@@ -244,6 +244,22 @@ export {
   type HkTooltipBridgeOptions,
   installHkImageFallback,
   type HkImageFallbackOptions,
+  reportHkRuntime,
+  getHkRuntimeEntry,
+  listHkRuntime,
+  readHkRuntime,
+  writeHkRuntime,
+  hkRuntimeSnapshot,
+  useHkRegistry,
+  type HkRuntimeKind,
+  type HkRuntimeStatus,
+  type HkRuntimeMeta,
+  type HkRuntimeEntryState,
+  type HkRuntimeReport,
+  type HkRuntimeHandle,
+  type HkRuntimeWriteOp,
+  type HkRuntimeSnapshot,
+  type HkRuntimeSnapshotEntry,
 } from "./runtime";
 
 // i18n

package/src/runtime/animationBus.ts

@@ -1,5 +1,7 @@
 import { setCssAnimationsEnabled } from "../animation/registerAnimations";
 
+import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
+
 export interface FrameContext {
   delta: number;
   elapsed: number;
@@ -81,6 +83,35 @@ function busyCount(): number {
   return syncEntries.size + normalEntries.size + idleEntries.size + intervalEntries.size + activeTransitions.size;
 }
 
+// Runtime-registry reporting (the "context of contexts"). Lazy: the bus
+// reports itself the first time anything schedules onto it and pulses on
+// every scheduling call / reduced-motion flip. The read facet exposes
+// live load (entries per tier, paused) and the write facet lets another
+// context or a host plugin flip reduced motion plugin-style via
+// writeHkRuntime("animationBus", { type: "setReducedMotion", value }).
+let runtimeReport: HkRuntimeHandle | null = null;
+function ensureRuntimeReport(): HkRuntimeHandle {
+  return (runtimeReport ??= reportHkRuntime("animationBus", {
+    kind: "bus",
+    description: "The shared rAF frame bus: sync/normal/idle tiers, one-shots, transitions and bus-ridden intervals.",
+    read: () => ({
+      sync: syncEntries.size,
+      normal: normalEntries.size,
+      idle: idleEntries.size,
+      intervals: intervalEntries.size,
+      transitions: activeTransitions.size,
+      paused,
+    }),
+    write: (op) => {
+      if (op.type === "setReducedMotion" && typeof op.value === "boolean") {
+        setReducedMotion(op.value);
+        return;
+      }
+      throw new Error(`unknown animationBus write op "${op.type}"`);
+    },
+  }));
+}
+
 function pickRegistry(priority: Priority): Map<string, Entry> {
   switch (priority) {
     case "sync": return syncEntries;
@@ -195,7 +226,10 @@ export function setReducedMotion(flag: boolean) {
   // the switch on every call so a direct setCssAnimationsEnabled(false)
   // from a performance-context caller is undone when motion resumes.
   setCssAnimationsEnabled(!flag);
-  if (paused === flag) return;
+  if (paused === flag) {
+    ensureRuntimeReport().pulse({ paused });
+    return;
+  }
   paused = flag;
   if (flag) {
     if (raf !== 0) {
@@ -209,6 +243,7 @@ export function setReducedMotion(flag: boolean) {
   } else {
     ensure();
   }
+  ensureRuntimeReport().pulse({ paused });
 }
 
 export function notifyScrollStart() {
@@ -225,6 +260,7 @@ export function onFrame(cb: Callback, priority: Priority = "sync"): AnimationHan
   const registry = pickRegistry(priority);
   registry.set(id, { cb, priority, lastRun: 0 });
   ensure();
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       registry.delete(id);
@@ -252,6 +288,7 @@ function pumpOneShots(now: number): void {
 export function onceFrame(cb: Callback): void {
   oneShotEntries.set(uid(), { cb, cancelled: false });
   ensureOneShotDrain();
+  ensureRuntimeReport().pulse();
 }
 
 export function scheduleFrame(cb: Callback): AnimationHandle {
@@ -259,6 +296,7 @@ export function scheduleFrame(cb: Callback): AnimationHandle {
   const id = uid();
   oneShotEntries.set(id, entry);
   ensureOneShotDrain();
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       entry.cancelled = true;
@@ -271,6 +309,7 @@ export function reportTransition(durationMs: number): AnimationHandle {
   const id = uid();
   activeTransitions.add(id);
   ensure();
+  ensureRuntimeReport().pulse();
   const timer = setTimeout(() => {
     activeTransitions.delete(id);
     halt();
@@ -288,6 +327,7 @@ export function scheduleEvery(cb: () => void, intervalMs: number): AnimationHand
   const id = uid();
   intervalEntries.set(id, { cb, interval: intervalMs, lastRun: 0, once: false });
   ensure();
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       intervalEntries.delete(id);
@@ -300,6 +340,7 @@ export function scheduleAfter(cb: () => void, delayMs: number): AnimationHandle
   const id = uid();
   intervalEntries.set(id, { cb, interval: delayMs, lastRun: performance.now(), once: true });
   ensure();
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       intervalEntries.delete(id);

package/src/runtime/cronBus.ts

@@ -1,12 +1,28 @@
+import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
+
 export interface CronHandle {
   disconnect(): void;
 }
 
+// Runtime-registry reporting (the "context of contexts"). Lazy: the bus
+// reports itself on first schedule and pulses on every schedule/
+// disconnect. Bare-timer cron has no inspectable state beyond its
+// liveness, which is exactly what the registry is for.
+let runtimeReport: HkRuntimeHandle | null = null;
+function ensureRuntimeReport(): HkRuntimeHandle {
+  return (runtimeReport ??= reportHkRuntime("cronBus", {
+    kind: "bus",
+    description: "The bare timer bus (setInterval/setTimeout passthrough) used by cron-grade callers like toast auto-dismiss.",
+  }));
+}
+
 export function scheduleCron(cb: () => void, intervalMs: number): CronHandle {
   const id = setInterval(cb, intervalMs);
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       clearInterval(id);
+      runtimeReport?.pulse();
     },
   };
 }
@@ -17,9 +33,11 @@ export function scheduleCronAfter(cb: () => void, delayMs: number): CronHandle {
     fired = true;
     cb();
   }, delayMs);
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       if (!fired) clearTimeout(id);
+      runtimeReport?.pulse();
     },
   };
 }

package/src/runtime/historySafetyNet.ts

@@ -22,6 +22,8 @@
  * next field occurrence can be attributed.
  */
 
+import { reportHkRuntime } from "./registry";
+
 /** Bare literals that read as a producer bug, never a real target. */
 const POISONED_LITERALS = new Set(["undefined", "null", "nan"]);
 
@@ -80,12 +82,47 @@ export function sanitizeHistoryUrl(
  *  harness) is detected and re-patched. */
 const PATCH_MARKER = "__hikariHistoryNet";
 
+// Runtime-registry reporting (the "context of contexts"): the net is
+// install-and-forget, so it reports itself on INSTALL (not at module
+// init — importing the module must not claim an installed hook) and
+// pulses on every (re)install and every coercion — the install
+// signature is unchanged. Coercions bump a running counter in the read
+// facet so field occurrences are countable from
+// readHkRuntime("historySafetyNet").
+let coercions = 0;
+let historyNetRuntime: ReturnType<typeof reportHkRuntime> | null = null;
+/** Options captured by the CURRENTLY-PATCHED closure. A re-install while
+ *  our patch is still on the prototype skips re-patching (the `continue`
+ *  below), so the first install's fallback/evidence stay in effect — the
+ *  registry meta must report THOSE, not the newest call's options, or it
+ *  would misreport the active fold target. */
+let activeFallback = "/";
+let activeEvidenceKey: string | false = DEFAULT_EVIDENCE_KEY;
+function ensureHistoryNetRuntime() {
+  return (historyNetRuntime ??= reportHkRuntime("historySafetyNet", {
+    kind: "hook",
+    description: "History.prototype pushState/replaceState net: off-origin or poisoned targets fold onto the app landing before the native call.",
+    read: () => ({ coercions }),
+  }));
+}
+
 /** Patch History.prototype. Safe to call multiple times: already-
  *  patched methods are left alone, but a method overwritten back to a
  *  foreign implementation is patched again (self-healing). */
 export function installHistorySafetyNet(options: HistorySafetyNetOptions = {}): void {
   const fallback = options.fallback ?? "/";
   const evidenceKey = options.evidenceKey === undefined ? DEFAULT_EVIDENCE_KEY : options.evidenceKey;
+  const alreadyPatched =
+    typeof (History.prototype as unknown as Record<string, unknown>).pushState === "function" &&
+    ((History.prototype as unknown as Record<string, unknown>).pushState as { [PATCH_MARKER]?: boolean })[PATCH_MARKER] === true;
+  if (!alreadyPatched) {
+    // Only an install that actually patches may claim its options as
+    // active; a no-op re-install keeps the first install's capture.
+    activeFallback = fallback;
+    activeEvidenceKey = evidenceKey;
+  }
+  ensureHistoryNetRuntime().setMeta({ fallback: activeFallback, evidenceKey: activeEvidenceKey === false ? "off" : activeEvidenceKey });
+  ensureHistoryNetRuntime().pulse();
   for (const method of ["pushState", "replaceState"] as const) {
     const current: unknown = (History.prototype as unknown as Record<string, unknown>)[method];
     if (
@@ -100,6 +137,8 @@ export function installHistorySafetyNet(options: HistorySafetyNetOptions = {}):
       const safe = sanitizeHistoryUrl(url, fallback);
       if (safe !== url) {
         const info: HistoryCoercion = { method, raw: String(url ?? ""), foldedTo: fallback };
+        coercions += 1;
+        historyNetRuntime?.pulse({ coercions });
         reportCoercion(info, evidenceKey, options);
       }
       return native.call(this, state as never, title, safe as never);

package/src/runtime/imageFallback.ts

@@ -27,6 +27,8 @@
 //     no src swap — for hosts that style the class themselves)
 import "./imageFallback.scss";
 
+import { reportHkRuntime } from "./registry";
+
 export interface HkImageFallbackOptions {
   /** Which images are covered. Default: `img`. */
   selector?: string;
@@ -57,6 +59,10 @@ interface FallbackState {
   selector: string;
   exclude: string;
   fallbackSrc: string;
+  /** How many images this install has re-rendered (registry meta). */
+  marked: number;
+  /** Runtime-registry handle for this install (the "context of contexts"). */
+  runtime?: ReturnType<typeof reportHkRuntime>;
 }
 
 const INSTALLS = new WeakMap<Document, FallbackState>();
@@ -72,6 +78,8 @@ function onError(state: FallbackState, e: Event) {
   if (state.fallbackSrc && target.getAttribute("src") !== state.fallbackSrc) {
     target.src = state.fallbackSrc;
   }
+  state.marked += 1;
+  state.runtime?.pulse({ marked: state.marked });
 }
 
 function onLoad(state: FallbackState, e: Event) {
@@ -91,12 +99,16 @@ function uninstall(state: FallbackState) {
   for (const [type, fn] of state.listeners.splice(0)) {
     state.root.removeEventListener(type, fn, true);
   }
+  state.runtime?.dispose();
 }
 
 /**
  * Install the document-level broken-image re-render. Returns the
  * uninstaller (removes listeners; already-marked images keep their
- * placeholder). Idempotent per document.
+ * placeholder). Idempotent per document. The install reports itself to
+ * the runtime registry (`imageFallback`, kind "hook") and pulses with a
+ * running `marked` count as images are re-rendered — the signature and
+ * options are unchanged.
  */
 export function installHkImageFallback(options: HkImageFallbackOptions = {}): () => void {
   if (typeof document === "undefined") return () => undefined;
@@ -109,7 +121,19 @@ export function installHkImageFallback(options: HkImageFallbackOptions = {}): ()
     selector: options.selector ?? "img",
     exclude: options.exclude ?? "[data-hk-img-native]",
     fallbackSrc: options.fallbackSrc !== undefined ? options.fallbackSrc : DEFAULT_FALLBACK_SRC,
+    marked: 0,
   };
+  state.runtime = reportHkRuntime("imageFallback", {
+    kind: "hook",
+    description: "Document-level broken-image re-render: swaps failed <img> loads for the muted placeholder tile.",
+    meta: {
+      selector: state.selector,
+      exclude: state.exclude,
+      fallback: state.fallbackSrc === "" ? "class-only" : state.fallbackSrc === DEFAULT_FALLBACK_SRC ? "bundled" : "custom",
+      marked: 0,
+    },
+    read: () => ({ installed: true, marked: state.marked }),
+  });
 
   // Resource errors never bubble — capture phase is the only delegation
   // point that sees them from the document.

package/src/runtime/index.ts

@@ -49,3 +49,21 @@ export { provideScrollWindow, useScrollWindow, type ScrollWindowContext } from "
 export { useReportedTransition, type ReportedTransition, type ReportedTransitionTrack } from "../composables/useReportedTransition";
 export { showProgressDialog, useProgressDialog, type ProgressDialogHandle, type ProgressDialogState } from "../composables/useProgressDialog";
 export { useSafeArea, type SafeAreaInsets } from "../composables/useSafeArea";
+export {
+  reportHkRuntime,
+  getHkRuntimeEntry,
+  listHkRuntime,
+  readHkRuntime,
+  writeHkRuntime,
+  hkRuntimeSnapshot,
+  useHkRegistry,
+  type HkRuntimeKind,
+  type HkRuntimeStatus,
+  type HkRuntimeMeta,
+  type HkRuntimeEntryState,
+  type HkRuntimeReport,
+  type HkRuntimeHandle,
+  type HkRuntimeWriteOp,
+  type HkRuntimeSnapshot,
+  type HkRuntimeSnapshotEntry,
+} from "./registry";

package/src/runtime/intervalBus.ts

@@ -29,6 +29,7 @@
  * burning down on a throttled timer.
  */
 import { onPageLifecycle } from "./pageLifecycle";
+import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
 
 export interface IntervalHandle {
   disconnect(): void;
@@ -46,6 +47,19 @@ interface Slot {
 const slots = new Set<Slot>();
 let lifecycleUnsub: (() => void) | null = null;
 
+// Runtime-registry reporting (the "context of contexts"). Lazy: the bus
+// reports itself on first schedule and pulses on every schedule/
+// disconnect, so polling liveness is answerable from
+// readHkRuntime("intervalBus") without importing this module.
+let runtimeReport: HkRuntimeHandle | null = null;
+function ensureRuntimeReport(): HkRuntimeHandle {
+  return (runtimeReport ??= reportHkRuntime("intervalBus", {
+    kind: "bus",
+    description: "The visibility-aware interval bus for data polling (parks while hidden, catches up on return).",
+    read: () => ({ slots: slots.size, once: Array.from(slots).filter((s) => s.once).length }),
+  }));
+}
+
 /** Run a slot callback with bus isolation: a throwing consumer is
  *  reported but never takes the shared timer/lifecycle machinery down
  *  (mirrors pageLifecycle's per-listener isolation). A repeat slot whose
@@ -149,12 +163,14 @@ export function scheduleInterval(cb: () => void, intervalMs: number): IntervalHa
   if (typeof document === "undefined" || !document.hidden) {
     arm(slot);
   }
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       slot.disconnected = true;
       park(slot);
       slots.delete(slot);
       maybePark();
+      runtimeReport?.pulse();
     },
   };
 }
@@ -178,12 +194,14 @@ export function scheduleIntervalAfter(cb: () => void, delayMs: number): Interval
   if (typeof document === "undefined" || !document.hidden) {
     arm(slot);
   }
+  ensureRuntimeReport().pulse();
   return {
     disconnect() {
       slot.disconnected = true;
       park(slot);
       slots.delete(slot);
       maybePark();
+      runtimeReport?.pulse();
     },
   };
 }

package/src/runtime/navigationGuard.ts

@@ -13,6 +13,7 @@
  */
 
 import { installHistorySafetyNet, type HistorySafetyNetOptions } from "./historySafetyNet";
+import { reportHkRuntime } from "./registry";
 
 /** Bare literals that read as a producer bug, never a real target. */
 const POISONED_LITERALS = new Set(["undefined", "null", "nan"]);
@@ -41,17 +42,34 @@ export interface NavigationSafetyNetOptions extends HistorySafetyNetOptions {
   router?: GuardRouter;
 }
 
+// Runtime-registry reporting (the "context of contexts"): the guard
+// reports itself on INSTALL (not at module init — importing the module
+// must not claim an installed guard) and counts blocked navigations —
+// the install signature is unchanged.
+let blocked = 0;
+let navGuardRuntime: ReturnType<typeof reportHkRuntime> | null = null;
+function ensureNavGuardRuntime() {
+  return (navGuardRuntime ??= reportHkRuntime("navigationGuard", {
+    kind: "hook",
+    description: "Router-level poisoned-target guard: bad navigation targets die as in-app redirects to the landing route.",
+    read: () => ({ blocked }),
+  }));
+}
+
 /** Register the beforeEach poisoned-target fold on a router. */
 export function createPoisonedLocationGuard(
   router: GuardRouter,
   fallback = "/",
 ): void {
+  ensureNavGuardRuntime();
   router.beforeEach((to: GuardRoute) => {
     const path = to.path ?? "";
     if (!path.startsWith("/") || POISONED_LITERALS.has(path)) {
       console.warn(
         `[Router] Blocked poisoned navigation target "${path}" (fullPath "${to.fullPath}") — redirecting to "${fallback}"`,
       );
+      blocked += 1;
+      navGuardRuntime?.pulse({ blocked });
       return fallback;
     }
     return true;
@@ -63,5 +81,7 @@ export function createPoisonedLocationGuard(
  *  navigation (module scope of the app's router setup is ideal). */
 export function installNavigationSafetyNet(options: NavigationSafetyNetOptions = {}): void {
   installHistorySafetyNet(options);
+  ensureNavGuardRuntime().setMeta({ routerGuard: Boolean(options.router), fallback: options.fallback ?? "/" });
+  ensureNavGuardRuntime().pulse();
   if (options.router) createPoisonedLocationGuard(options.router, options.fallback ?? "/");
 }