@celestia-island/hikari 0.46.0 → 0.47.0

package/src/runtime/pageLifecycle.ts

@@ -14,6 +14,8 @@
  */
 import { readonly, ref, type Ref } from "vue";
 
+import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
+
 interface PageLifecycleState {
   visible: boolean;
   online: boolean;
@@ -26,11 +28,24 @@ let installed = false;
 type LifecycleListener = (state: PageLifecycleState) => void;
 const listeners = new Set<LifecycleListener>();
 
+// Runtime-registry reporting (the "context of contexts"). Lazy: the
+// lifecycle context reports itself on first subscribe/probe and pulses
+// on every visibility/online transition it fans out.
+let runtimeReport: HkRuntimeHandle | null = null;
+function ensureRuntimeReport(): HkRuntimeHandle {
+  return (runtimeReport ??= reportHkRuntime("pageLifecycle", {
+    kind: "context",
+    description: "The page lifecycle context: visibility + online/offline state fanned out to framework-free listeners.",
+    read: () => ({ ...currentState(), listeners: listeners.size }),
+  }));
+}
+
 function currentState(): PageLifecycleState {
   return { visible: visible.value, online: online.value };
 }
 
 function notify(): void {
+  runtimeReport?.pulse({ ...currentState() });
   const snapshot = currentState();
   for (const listener of listeners) {
     try {
@@ -66,6 +81,7 @@ export function usePageLifecycle(): {
   online: Readonly<Ref<boolean>>;
 } {
   install();
+  ensureRuntimeReport();
   return { visible: readonly(visible), online: readonly(online) };
 }
 
@@ -76,15 +92,19 @@ export function usePageLifecycle(): {
  */
 export function onPageLifecycle(listener: LifecycleListener): () => void {
   install();
+  ensureRuntimeReport();
   listeners.add(listener);
   return () => {
     listeners.delete(listener);
   };
 }
 
-/** Imperative probe — no subscription. */
+/** Imperative probe — no subscription. Reports to the runtime registry
+ * too, so an install-through-probe (no subscriber ever) is still
+ * observable. */
 export function pageLifecycleState(): PageLifecycleState {
   install();
+  ensureRuntimeReport();
   return currentState();
 }
 

package/src/runtime/registry.integration.test.ts

@@ -0,0 +1,309 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { setLocale } from "../i18n/context";
+import {
+  getHkRuntimeEntry,
+  hkRuntimeSnapshot,
+  readHkRuntime,
+  writeHkRuntime,
+} from "./registry";
+import { installHkImageFallback } from "./imageFallback";
+import { onFrame, setReducedMotion } from "./animationBus";
+import { scheduleInterval } from "./intervalBus";
+import { installHkTooltipBridge } from "./tooltipBridge";
+import { installHistorySafetyNet } from "./historySafetyNet";
+import { installNavigationSafetyNet } from "./navigationGuard";
+import { usePopupManager } from "./usePopupManager";
+import { useOverlay } from "./useOverlay";
+import { useToast } from "./useToast";
+import { clearErrorReportingState, reportError } from "../errorReporting/state";
+import { clearBlockingToasts, showBlockingToast } from "./useBlockingToast";
+import { onPageLifecycle, pageLifecycleState } from "./pageLifecycle";
+import { showProgressDialog } from "../composables/useProgressDialog";
+
+/**
+ * Integration contract: every hikari global context / hook / bus reports
+ * itself to the runtime registry (the "context of contexts") WITHOUT its
+ * registration API changing, pulses on activity, and exposes its global
+ * state for cross-context read/write through the registry.
+ */
+
+const uninstalls: Array<() => void> = [];
+
+afterEach(() => {
+  for (const u of uninstalls.splice(0)) u();
+  setReducedMotion(false);
+  clearErrorReportingState();
+});
+
+describe("i18n context auto-report", () => {
+  it("registers at module init as a live context", () => {
+    const entry = getHkRuntimeEntry("i18n");
+    expect(entry).toBeDefined();
+    expect(entry!.status).toBe("active");
+    expect(entry!.kind).toBe("context");
+    const state = readHkRuntime("i18n");
+    expect(typeof state!.locale).toBe("string");
+    expect(typeof state!.keys).toBe("number");
+  });
+
+  it("pulses and updates the read facet on locale switches", async () => {
+    const before = getHkRuntimeEntry("i18n")!.pulses;
+    await setLocale("zh-CN");
+    const after = getHkRuntimeEntry("i18n")!;
+    expect(after.pulses).toBeGreaterThan(before);
+    expect(readHkRuntime("i18n")!.locale).toBe("zh-CN");
+    await setLocale("en");
+  });
+
+  it("supports plugin-style steering through the write facet", async () => {
+    expect(writeHkRuntime("i18n", { type: "setLocale", locale: "ja" })).toBe(true);
+    expect(readHkRuntime("i18n")!.locale).toBe("ja");
+    expect(writeHkRuntime("i18n", { type: "nonsense" })).toBe(false);
+    await setLocale("en");
+  });
+});
+
+describe("popup manager (modal context) auto-report", () => {
+  it("reports lazily on first use and counts live popups per kind", () => {
+    const manager = usePopupManager();
+    expect(getHkRuntimeEntry("popupManager")).toBeDefined();
+    const handleA = manager.register("modal", true, "Settings");
+    const handleB = manager.register("dropdown");
+    const state = readHkRuntime("popupManager")!;
+    expect(state.open).toBe(2);
+    expect((state.byKind as Record<string, number>).modal).toBe(1);
+    expect((state.byKind as Record<string, number>).dropdown).toBe(1);
+    expect(state.scrollLocks).toBe(1);
+    manager.unregister(handleA.id);
+    manager.unregister(handleB.id);
+    expect(readHkRuntime("popupManager")!.open).toBe(0);
+  });
+
+  it("pulses on register/unregister", () => {
+    const manager = usePopupManager();
+    const before = getHkRuntimeEntry("popupManager")!.pulses;
+    const handle = manager.register("tooltip");
+    manager.unregister(handle.id);
+    expect(getHkRuntimeEntry("popupManager")!.pulses).toBeGreaterThanOrEqual(before + 2);
+  });
+});
+
+describe("overlay context auto-report", () => {
+  it("reports lazily on first use and lists open overlay names", () => {
+    const overlay = useOverlay({ name: "hk-test-select" });
+    overlay.open();
+    const state = readHkRuntime("overlay")!;
+    expect(state.open).toBe(1);
+    expect(state.names).toContain("hk-test-select");
+    overlay.close();
+    expect(readHkRuntime("overlay")!.open).toBe(0);
+  });
+});
+
+describe("toast context auto-report", () => {
+  it("reports lazily on first use and counts slots/messages", () => {
+    const toast = useToast();
+    toast.info("hello");
+    toast.error("bad");
+    const state = readHkRuntime("toast")!;
+    expect(state.slots).toBe(2);
+    expect(state.messages).toBe(2);
+    expect(getHkRuntimeEntry("toast")!.pulses).toBeGreaterThan(0);
+  });
+
+  it("an unknown-id remove is a full no-op — no pulse, no state change", () => {
+    const { remove } = useToast();
+    const pulsesBefore = getHkRuntimeEntry("toast")!.pulses;
+    const slotsBefore = readHkRuntime("toast")!.slots;
+    remove(999999);
+    expect(getHkRuntimeEntry("toast")!.pulses).toBe(pulsesBefore);
+    expect(readHkRuntime("toast")!.slots).toBe(slotsBefore);
+  });
+});
+
+describe("image fallback hook auto-report", () => {
+  it("reports on install, pulses with a running marked count, disposes on uninstall", () => {
+    expect(getHkRuntimeEntry("imageFallback")?.status ?? "absent").not.toBe("active");
+    const uninstall = installHkImageFallback();
+    uninstalls.push(uninstall);
+
+    const entry = getHkRuntimeEntry("imageFallback")!;
+    expect(entry.kind).toBe("hook");
+    expect(entry.status).toBe("active");
+    expect(entry.meta.fallback).toBe("bundled");
+
+    const el = document.createElement("img");
+    el.src = "https://example.invalid/pic.png";
+    document.body.appendChild(el);
+    el.dispatchEvent(new Event("error"));
+
+    expect(entry.meta.marked).toBe(1);
+    expect(readHkRuntime("imageFallback")).toEqual({ installed: true, marked: 1 });
+    el.remove();
+
+    uninstall();
+    expect(getHkRuntimeEntry("imageFallback")!.status).toBe("disposed");
+    expect(readHkRuntime("imageFallback")).toBeUndefined();
+  });
+});
+
+describe("tooltip bridge hook auto-report", () => {
+  it("reports on install with options meta and disposes on uninstall", () => {
+    const uninstall = installHkTooltipBridge({ delay: 10, placement: "bottom" });
+    uninstalls.push(uninstall);
+    const entry = getHkRuntimeEntry("tooltipBridge")!;
+    expect(entry.kind).toBe("hook");
+    expect(entry.status).toBe("active");
+    expect(entry.meta.delay).toBe(10);
+    expect(entry.meta.placement).toBe("bottom");
+    uninstall();
+    expect(getHkRuntimeEntry("tooltipBridge")!.status).toBe("disposed");
+  });
+});
+
+describe("animation bus auto-report", () => {
+  it("reports lazily on first schedule and exposes live load", () => {
+    const handle = onFrame(() => undefined, "normal");
+    const entry = getHkRuntimeEntry("animationBus");
+    expect(entry).toBeDefined();
+    expect(entry!.kind).toBe("bus");
+    expect((readHkRuntime("animationBus")!.normal as number) >= 1).toBe(true);
+    handle.disconnect();
+  });
+
+  it("supports plugin-style reduced-motion steering through the write facet", () => {
+    onFrame(() => undefined); // activate the bus's registry entry
+    expect(writeHkRuntime("animationBus", { type: "setReducedMotion", value: true })).toBe(true);
+    expect(readHkRuntime("animationBus")!.paused).toBe(true);
+    expect(writeHkRuntime("animationBus", { type: "setReducedMotion", value: false })).toBe(true);
+    expect(readHkRuntime("animationBus")!.paused).toBe(false);
+    expect(writeHkRuntime("animationBus", { type: "warp" })).toBe(false);
+  });
+});
+
+describe("interval bus auto-report", () => {
+  it("reports lazily on first schedule with live slot counts", () => {
+    const handle = scheduleInterval(() => undefined, 60_000);
+    const entry = getHkRuntimeEntry("intervalBus");
+    expect(entry).toBeDefined();
+    expect(readHkRuntime("intervalBus")!.slots).toBe(1);
+    handle.disconnect();
+    expect(readHkRuntime("intervalBus")!.slots).toBe(0);
+  });
+});
+
+describe("blocking toast context auto-report", () => {
+  afterEach(() => clearBlockingToasts());
+
+  it("reports lazily on first prompt and counts pending gates", () => {
+    expect(getHkRuntimeEntry("blockingToast")?.status ?? "absent").not.toBe("active");
+    void showBlockingToast("join this group?");
+    expect(getHkRuntimeEntry("blockingToast")!.kind).toBe("context");
+    expect(readHkRuntime("blockingToast")!.pending).toBe(1);
+    clearBlockingToasts();
+    expect(readHkRuntime("blockingToast")!.pending).toBe(0);
+  });
+});
+
+describe("page lifecycle context auto-report", () => {
+  it("reports (lazily, or via a sibling bus) and exposes visibility/online state", () => {
+    // NOTE: no "not active before" precondition here — the interval bus
+    // subscribes to the lifecycle internally, so any earlier test that
+    // touched it has already activated this entry. That transitive
+    // activation is exactly the auto-report behavior under test.
+    const unsubscribe = onPageLifecycle(() => undefined);
+    const entry = getHkRuntimeEntry("pageLifecycle")!;
+    expect(entry.kind).toBe("context");
+    expect(entry.status).toBe("active");
+    const state = readHkRuntime("pageLifecycle")!;
+    expect(typeof state.visible).toBe("boolean");
+    expect(typeof state.online).toBe("boolean");
+    expect(state.listeners).toBe(1);
+    unsubscribe();
+    expect(readHkRuntime("pageLifecycle")!.listeners).toBe(0);
+    expect(pageLifecycleState().visible).toBe(true);
+  });
+});
+
+describe("error reporting plugin auto-report", () => {
+  it("reports at module init and counts accepted errors in the read facet", () => {
+    const entry = getHkRuntimeEntry("errorReporting");
+    expect(entry).toBeDefined();
+    expect(entry!.kind).toBe("plugin");
+    const before = readHkRuntime("errorReporting")!.reports as number;
+    reportError(new Error("registry-test"), "manual");
+    const state = readHkRuntime("errorReporting")!;
+    expect(state.reports).toBe(before + 1);
+    expect(state.landingUp).toBe(true);
+    expect((state.current as { message: string }).message).toBe("registry-test");
+    // First-error-wins: a second error while the landing is up logs but
+    // does NOT count as accepted.
+    reportError(new Error("registry-test-2"), "manual");
+    expect(readHkRuntime("errorReporting")!.reports).toBe(before + 1);
+    expect((readHkRuntime("errorReporting")!.current as { message: string }).message).toBe("registry-test");
+  });
+});
+
+describe("safety-net hooks report on install, not on import", () => {
+  // ONE test for the whole safety-net family on purpose: the "not active
+  // before install" premise is only sound while no sibling test has
+  // installed either net (installNavigationSafetyNet internally installs
+  // the history net), so every install in this file lives HERE — split
+  // tests were order-dependent under --sequence.shuffle.
+  it("nets become active only when installed; meta reports the ACTIVE patch's options", () => {
+    // Importing the modules (which this file did transitively) must not
+    // claim installed hooks.
+    expect(getHkRuntimeEntry("historySafetyNet")?.status ?? "absent").not.toBe("active");
+    expect(getHkRuntimeEntry("navigationGuard")?.status ?? "absent").not.toBe("active");
+
+    installHistorySafetyNet();
+    const historyEntry = getHkRuntimeEntry("historySafetyNet")!;
+    expect(historyEntry.kind).toBe("hook");
+    expect(historyEntry.status).toBe("active");
+    expect(historyEntry.meta.fallback).toBe("/");
+    // The history net alone must not claim the router guard.
+    expect(getHkRuntimeEntry("navigationGuard")?.status ?? "absent").not.toBe("active");
+
+    installNavigationSafetyNet();
+    const navEntry = getHkRuntimeEntry("navigationGuard")!;
+    expect(navEntry.kind).toBe("hook");
+    expect(navEntry.status).toBe("active");
+    expect(navEntry.meta.routerGuard).toBe(false);
+
+    // A no-op re-install with a DIFFERENT fallback cannot change the
+    // live closure (installs are idempotent) — the meta must not claim
+    // the new target either.
+    installHistorySafetyNet({ fallback: "/no-op-reinstall-target" });
+    expect(getHkRuntimeEntry("historySafetyNet")!.meta.fallback).not.toBe("/no-op-reinstall-target");
+  });
+});
+
+describe("progress dialog context auto-report", () => {
+  it("reports lazily on first show and exposes the live dialog state", () => {
+    expect(getHkRuntimeEntry("progressDialog")?.status ?? "absent").not.toBe("active");
+    const dialog = showProgressDialog({ title: "Deploying" });
+    dialog.log("step 1");
+    dialog.log("step 2");
+    const state = readHkRuntime("progressDialog")!;
+    expect(state.open).toBe(true);
+    expect(state.title).toBe("Deploying");
+    expect(state.logLines).toBe(2);
+    dialog.close();
+    expect(readHkRuntime("progressDialog")!.open).toBe(false);
+  });
+});
+
+describe("whole-registry debug snapshot", () => {
+  it("captures every reporting subsystem with live state", () => {
+    const uninstall = installHkImageFallback();
+    uninstalls.push(uninstall);
+    usePopupManager();
+    const snap = hkRuntimeSnapshot();
+    const ids = snap.entries.filter((e) => e.status === "active").map((e) => e.id);
+    for (const expected of ["i18n", "popupManager", "imageFallback", "errorReporting"]) {
+      expect(ids).toContain(expected);
+    }
+    expect(() => JSON.stringify(snap)).not.toThrow();
+  });
+});

package/src/runtime/registry.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getHkRuntimeEntry,
+  hkRuntimeSnapshot,
+  listHkRuntime,
+  readHkRuntime,
+  reportHkRuntime,
+  useHkRegistry,
+  writeHkRuntime,
+} from "./registry";
+
+/**
+ * Core registry contract tests (the "context of contexts"):
+ * - report is an idempotent upsert while active: facets refresh, but
+ *   registeredAt and the pulse history survive a re-report
+ * - dispose marks the entry disposed and drops its facets; the record
+ *   stays listed for post-mortem debugging
+ * - a re-report AFTER dispose starts a fresh lifetime; stale handles
+ *   from the previous lifetime can neither pulse nor dispose the new one
+ * - pulse bumps pulses/lastActiveAt and shallow-merges meta
+ * - read/write facets: cross-context access, unknown ids, throwing
+ *   facets and unknown op types all degrade without throwing
+ * - list/snapshot are stable-ordered plain clones
+ */
+
+describe("reportHkRuntime", () => {
+  it("registers an active entry with kind, description and meta", () => {
+    const h = reportHkRuntime("test.core.basic", {
+      kind: "hook",
+      description: "a test hook",
+      meta: { flavor: "mint" },
+    });
+    expect(h.id).toBe("test.core.basic");
+    const entry = getHkRuntimeEntry("test.core.basic");
+    expect(entry).toBeDefined();
+    expect(entry!.status).toBe("active");
+    expect(entry!.kind).toBe("hook");
+    expect(entry!.description).toBe("a test hook");
+    expect(entry!.meta).toEqual({ flavor: "mint" });
+    expect(entry!.pulses).toBe(0);
+    expect(entry!.registeredAt).toBeGreaterThan(0);
+    h.dispose();
+  });
+
+  it("re-report while active keeps the lifetime (registeredAt, pulses) and refreshes facets", () => {
+    const first = reportHkRuntime("test.core.upsert", {
+      kind: "context",
+      meta: { v: 1 },
+      read: () => ({ v: 1 }),
+    });
+    first.pulse();
+    first.pulse();
+    const before = getHkRuntimeEntry("test.core.upsert")!;
+    const registeredAt = before.registeredAt;
+
+    const second = reportHkRuntime("test.core.upsert", {
+      kind: "context",
+      description: "refreshed",
+      meta: { v: 2 },
+      read: () => ({ v: 2 }),
+    });
+    const after = getHkRuntimeEntry("test.core.upsert")!;
+    expect(after.registeredAt).toBe(registeredAt);
+    expect(after.pulses).toBe(2);
+    expect(readHkRuntime("test.core.upsert")).toEqual({ v: 2 });
+    // Both handles address the SAME live entry.
+    second.pulse();
+    expect(getHkRuntimeEntry("test.core.upsert")!.pulses).toBe(3);
+    first.dispose();
+    expect(getHkRuntimeEntry("test.core.upsert")!.status).toBe("disposed");
+  });
+
+  it("dispose drops the facets but keeps the record listed for debugging", () => {
+    const h = reportHkRuntime("test.core.dispose", {
+      kind: "hook",
+      meta: { a: 1 },
+      read: () => ({ a: 1 }),
+      write: () => undefined,
+    });
+    h.dispose();
+    const entry = getHkRuntimeEntry("test.core.dispose")!;
+    expect(entry.status).toBe("disposed");
+    // Record survives; facets do not.
+    expect(listHkRuntime().some((e) => e.id === "test.core.dispose" && e.status === "disposed")).toBe(true);
+    expect(readHkRuntime("test.core.dispose")).toBeUndefined();
+    expect(writeHkRuntime("test.core.dispose", { type: "x" })).toBe(false);
+    // Idempotent: disposing twice is safe.
+    h.dispose();
+    expect(entry.status).toBe("disposed");
+  });
+
+  it("late pulses from a disposed lifetime are no-ops", () => {
+    const h = reportHkRuntime("test.core.latePulse", { kind: "hook" });
+    h.pulse();
+    h.dispose();
+    h.pulse(); // a subsystem tearing down asynchronously must not resurrect
+    const entry = getHkRuntimeEntry("test.core.latePulse")!;
+    expect(entry.status).toBe("disposed");
+    expect(entry.pulses).toBe(1);
+  });
+
+  it("re-report after dispose starts a fresh lifetime; stale handles cannot touch it", async () => {
+    const stale = reportHkRuntime("test.core.rebirth", {
+      kind: "hook",
+      read: () => ({ gen: 1 }),
+    });
+    stale.pulse();
+    stale.dispose();
+
+    const fresh = reportHkRuntime("test.core.rebirth", {
+      kind: "hook",
+      read: () => ({ gen: 2 }),
+    });
+    const entry = getHkRuntimeEntry("test.core.rebirth")!;
+    expect(entry.status).toBe("active");
+    expect(entry.pulses).toBe(0);
+    expect(readHkRuntime("test.core.rebirth")).toEqual({ gen: 2 });
+
+    stale.pulse(); // previous epoch — must be ignored
+    expect(entry.pulses).toBe(0);
+    stale.dispose(); // previous epoch — must not kill the fresh entry
+    expect(entry.status).toBe("active");
+    fresh.dispose();
+  });
+});
+
+describe("pulse", () => {
+  it("bumps pulses, refreshes lastActiveAt and shallow-merges meta", async () => {
+    const h = reportHkRuntime("test.core.pulse", {
+      kind: "bus",
+      meta: { count: 0, extra: "keep" },
+    });
+    // getHkRuntimeEntry returns a LIVE readonly view — capture scalars,
+    // not the proxy, for before/after comparisons.
+    const before = getHkRuntimeEntry("test.core.pulse")!;
+    const pulsesBefore = before.pulses;
+    const lastActiveBefore = before.lastActiveAt;
+    await new Promise((r) => setTimeout(r, 2));
+    h.pulse({ count: 1 });
+    const after = getHkRuntimeEntry("test.core.pulse")!;
+    expect(after.pulses).toBe(pulsesBefore + 1);
+    expect(after.lastActiveAt).toBeGreaterThan(lastActiveBefore);
+    expect(after.meta).toEqual({ count: 1, extra: "keep" });
+    h.dispose();
+  });
+
+  it("setMeta merges without counting a pulse", () => {
+    const h = reportHkRuntime("test.core.setMeta", { kind: "bus", meta: { a: 1 } });
+    h.setMeta({ b: 2 });
+    const entry = getHkRuntimeEntry("test.core.setMeta")!;
+    expect(entry.meta).toEqual({ a: 1, b: 2 });
+    expect(entry.pulses).toBe(0);
+    h.dispose();
+  });
+});
+
+describe("cross-context read/write", () => {
+  it("reads a live facet and returns undefined for unknown ids", () => {
+    expect(readHkRuntime("test.core.neverRegistered")).toBeUndefined();
+    const h = reportHkRuntime("test.core.read", {
+      kind: "context",
+      read: () => ({ now: Date.now() >= 0 }),
+    });
+    expect(readHkRuntime("test.core.read")).toEqual({ now: true });
+    h.dispose();
+  });
+
+  it("a throwing read facet degrades to undefined instead of crashing", () => {
+    const h = reportHkRuntime("test.core.badRead", {
+      kind: "context",
+      read: () => {
+        throw new Error("boom");
+      },
+    });
+    expect(readHkRuntime("test.core.badRead")).toBeUndefined();
+    h.dispose();
+  });
+
+  it("applies write ops and reports false for unknown ids / missing facets / rejected ops", () => {
+    expect(writeHkRuntime("test.core.unknown", { type: "x" })).toBe(false);
+    let calls: string[] = [];
+    const h = reportHkRuntime("test.core.write", {
+      kind: "plugin",
+      write: (op) => {
+        if (op.type === "go") {
+          calls.push("go");
+          return;
+        }
+        throw new Error(`unknown op ${op.type}`);
+      },
+    });
+    expect(writeHkRuntime("test.core.write", { type: "go" })).toBe(true);
+    expect(calls).toEqual(["go"]);
+    expect(writeHkRuntime("test.core.write", { type: "nope" })).toBe(false);
+    expect(calls).toEqual(["go"]);
+    h.dispose();
+    // disposed → no facet anymore
+    expect(writeHkRuntime("test.core.write", { type: "go" })).toBe(false);
+    calls = [];
+  });
+});
+
+describe("list / snapshot", () => {
+  it("lists plain, stable-ordered clones that do not alias live state", () => {
+    const h1 = reportHkRuntime("test.core.listA", { kind: "hook" });
+    const h2 = reportHkRuntime("test.core.listB", { kind: "bus" });
+    const ids = listHkRuntime().map((e) => e.id);
+    expect(ids.indexOf("test.core.listA")).toBeLessThan(ids.indexOf("test.core.listB"));
+    const clone = listHkRuntime().find((e) => e.id === "test.core.listA")!;
+    h1.pulse();
+    expect(clone.pulses).toBe(0); // clone, not the reactive state
+    expect(getHkRuntimeEntry("test.core.listA")!.pulses).toBe(1);
+    h1.dispose();
+    h2.dispose();
+  });
+
+  it("snapshot embeds the live read facet under `state`", () => {
+    const h = reportHkRuntime("test.core.snap", {
+      kind: "context",
+      meta: { locale: "en" },
+      read: () => ({ deep: { live: true } }),
+    });
+    const snap = hkRuntimeSnapshot();
+    const entry = snap.entries.find((e) => e.id === "test.core.snap");
+    expect(entry).toBeDefined();
+    expect(entry!.meta).toEqual({ locale: "en" });
+    expect(entry!.state).toEqual({ deep: { live: true } });
+    expect(snap.generatedAt).toBeGreaterThan(0);
+    h.dispose();
+  });
+
+  it("snapshot stays JSON-serializable", () => {
+    const h = reportHkRuntime("test.core.json", {
+      kind: "hook",
+      meta: { n: 1, s: "x", b: true, arr: [1, 2] },
+      read: () => ({ ok: 1 }),
+    });
+    expect(() => JSON.stringify(hkRuntimeSnapshot())).not.toThrow();
+    h.dispose();
+  });
+});
+
+describe("useHkRegistry", () => {
+  it("exposes a reactive entries computed plus the plain accessors", () => {
+    const h = reportHkRuntime("test.core.vue", { kind: "context" });
+    const { entries, read, write, snapshot } = useHkRegistry();
+    expect(entries.value.some((e) => e.id === "test.core.vue")).toBe(true);
+    expect(read("test.core.vue")).toBeUndefined(); // no read facet declared
+    expect(write("test.core.vue", { type: "x" })).toBe(false);
+    expect(snapshot().entries.some((e) => e.id === "test.core.vue")).toBe(true);
+    h.dispose();
+  });
+
+  it("the entries computed sees BRAND-NEW registrations (structural version)", () => {
+    const { entries } = useHkRegistry();
+    const before = entries.value.some((e) => e.id === "test.core.lateArrival");
+    expect(before).toBe(false);
+    const h = reportHkRuntime("test.core.lateArrival", { kind: "hook" });
+    // The computed must invalidate on the structural change itself —
+    // before this fix it only tracked already-known reactive states, so
+    // a debug panel missed first-time registrations until something
+    // pulsed.
+    expect(entries.value.some((e) => e.id === "test.core.lateArrival")).toBe(true);
+    h.dispose();
+    expect(entries.value.find((e) => e.id === "test.core.lateArrival")?.status).toBe("disposed");
+  });
+
+  it("lists entries in true registration order (sequence, not clock)", () => {
+    const h1 = reportHkRuntime("test.core.seqZ", { kind: "hook" });
+    const h2 = reportHkRuntime("test.core.seqA", { kind: "hook" });
+    const ids = listHkRuntime().map((e) => e.id);
+    // seqZ registered FIRST — must stay first even though it sorts after
+    // seqA alphabetically (same-millisecond installs used to invert).
+    expect(ids.indexOf("test.core.seqZ")).toBeLessThan(ids.indexOf("test.core.seqA"));
+    h1.dispose();
+    h2.dispose();
+  });
+});