pi-weave 0.1.7 → 0.1.8

package/src/web/client/graph/renderer.ts

@@ -0,0 +1,279 @@
+/**
+ * The renderer seam (weave-workspace §7.5).
+ *
+ * > `src/web/client/graph/renderer.ts` exposes a narrow interface — `mount`,
+ * > `setGraph(nodes, edges, positions)`, `setHighlight(Set<id>)`, `onSelect`,
+ * > `fit`, `destroy` — with `SigmaRenderer` as the only implementation. If
+ * > sigma ever stops being the right answer, one file changes.
+ *
+ * That is handoff design goal #5 (decouple simulation / rendering /
+ * interaction) satisfied *structurally* rather than by discipline. The column
+ * above holds a {@link GraphRenderer} and never a `Sigma`; §8 keeps layout
+ * correctness independent of the renderer entirely.
+ *
+ * ## Why `new Sigma(...)` is a parameter
+ *
+ * §10 forbids a DOM test environment, and sigma needs a canvas and a WebGL
+ * context — so the naive shape of this file (interface, then a
+ * `createSigmaRenderer` that calls `new Sigma`) is a file that reports **0 %
+ * coverage as a whole**, because it cannot even be imported. Verified rather
+ * than assumed: `import Sigma from "sigma"` evaluates
+ * `WebGL2RenderingContext.BOOL` at module scope while building its default
+ * program table, so the import alone is a `ReferenceError` in Node, before a
+ * line of ours runs.
+ *
+ * That is a worse outcome than it looks. This repository's rule (§10, and
+ * `docs/testing.md` §L5.2) is that *untestable lines* are kept to a handful,
+ * not that untestable *files* are excluded — the one coverage exclusion that
+ * exists is a type-only module, and a blanket `src/web/client/**` exclude is
+ * explicitly "not acceptable". A whole renderer sitting outside the gate would
+ * be exactly the erosion that rule prevents.
+ *
+ * So the dependency is inverted. {@link SigmaLike} and {@link SigmaFactory}
+ * are the two-and-a-half-method port sigma satisfies structurally;
+ * {@link sigmaRenderer} is the entire renderer written against the port, and
+ * it is covered by ordinary unit tests with a recording fake. The only thing
+ * that genuinely cannot be tested is the four-line adapter in
+ * `renderer.dom.ts` that says `new Sigma(graph, container, settings)` — the
+ * same shape, and the same reasoning, as `api.dom.ts` for `fetch` and
+ * `domEventSource` for `EventSource`.
+ *
+ * §7.5's promise is unaffected. "One file changes" is still true, and it is
+ * now true of a file with no branches in it.
+ *
+ * ## Tier rules (§2)
+ *
+ * `src/web/client/**`. This file imports no npm package at all, which is what
+ * lets the root `tsconfig.json` project (no `DOM` lib) compile the tests that
+ * import it.
+ */
+
+import type { Point } from "../../shared/layout";
+import type { ColorScheme, EdgeDisplayOverride, GraphSettings, NodeDisplayOverride, RenderEdge, RenderGraph, RenderNode } from "./graph.model";
+import { edgeReducer, graphSettings, nodeReducer } from "./graph.model";
+import type { ProjectedGraph } from "./project";
+import { positionsOf, project, syncPositions } from "./project";
+
+// --- the seam -------------------------------------------------------------------
+
+/**
+ * The narrow interface §7.5 specifies.
+ *
+ * `setGraph` takes a {@link RenderGraph} rather than §7.5's literal
+ * `(nodes, edges, positions)` triple, and that is the one deviation worth
+ * naming. The triple would make every implementation re-derive colours, sizes
+ * and labels from raw wire nodes — i.e. it would put the decisions §7.5 wants
+ * decoupled *behind* the seam. Passing the already-decided model keeps the
+ * argument list to one and the second implementation, if there ever is one,
+ * honest.
+ */
+export interface GraphRenderer {
+  /** Attach to a container. Idempotent: mounting twice is a no-op. */
+  mount(container: RenderContainer): void;
+  /** Replace the drawn graph. Safe before {@link mount}. */
+  setGraph(graph: RenderGraph): void;
+  /**
+   * Move nodes without rebuilding.
+   *
+   * Separate from {@link setGraph} because a re-run of the simulation over an
+   * unchanged node set is the common case (drag, expand, resize) and
+   * rebuilding would drop the camera and every WebGL buffer.
+   */
+  setPositions(positions: ReadonlyMap<string, Point>): void;
+  /**
+   * Dim everything outside this set (§7.4). `null` clears the highlight.
+   *
+   * `null` is not the empty set: nothing selected means everything renders
+   * normally, an empty neighbourhood means everything dims. See
+   * `graph.model.ts`'s `nodeReducer`.
+   */
+  setHighlight(highlight: ReadonlySet<string> | null): void;
+  /** Called with a node id on click, and with `null` on a click off any node. */
+  onSelect(handler: (id: string | null) => void): void;
+  /** Frame the whole graph. The `[fit]` control. */
+  fit(): void;
+  /** Current positions, for warm-starting a re-run. */
+  positions(): Map<string, Point>;
+  /** Tear down. Idempotent, and must leave no listener behind. */
+  destroy(): void;
+}
+
+/**
+ * The container, as far as this seam is concerned.
+ *
+ * Sigma wants an `HTMLElement`, and this file may not say so — a test
+ * importing it drags the module into the **root** `tsconfig.json` project
+ * (`exclude` filters the initial glob, not what an included file imports), and
+ * that project has no `DOM` lib. The structural stand-in is the same trick
+ * `cssvars.ts`, `api.ts` and `live.ts` use; the one cast lives in
+ * `renderer.dom.ts`, which is compiled only by `tsconfig.web.json`.
+ */
+export interface RenderContainer {
+  readonly clientWidth: number;
+  readonly clientHeight: number;
+}
+
+/**
+ * A renderer that draws nothing.
+ *
+ * Not a test double — a production path. The graph column renders before its
+ * container exists (the first pass), may never mount at all (the `medium`
+ * breakpoint collapses the column), and must keep working when it does not. A
+ * null object removes the `renderer === null` check from every call site,
+ * which is the check that is always missing from exactly one of them.
+ */
+export function nullRenderer(): GraphRenderer {
+  return {
+    mount() {},
+    setGraph() {},
+    setPositions() {},
+    setHighlight() {},
+    onSelect() {},
+    fit() {},
+    positions() {
+      return new Map();
+    },
+    destroy() {},
+  };
+}
+
+/**
+ * How a {@link GraphRenderer} is obtained.
+ *
+ * Injected at the column rather than imported by it, so the graph column is
+ * driven by a recording fake in a test and by `createSigmaRenderer` in the
+ * browser — the same port-shaped injection `api.ts` uses for `fetch`.
+ */
+export type RendererFactory = (scheme: ColorScheme) => GraphRenderer;
+
+// --- the sigma port -----------------------------------------------------------------
+
+/**
+ * The camera, as far as this module uses it.
+ *
+ * One method. `animatedReset` is what `[fit]` is (§7.4: "Pan / zoom / fit →
+ * `camera.animatedReset()`").
+ */
+export interface CameraLike {
+  animatedReset(): Promise<void>;
+}
+
+/**
+ * The slice of `Sigma` this renderer drives.
+ *
+ * Structural, so the real class satisfies it without a cast and a fake is an
+ * object literal — the same reasoning `EventSourceLike` in `live.ts` records.
+ * Six methods, and every one of them is called below, so the port cannot grow
+ * a member nothing uses.
+ *
+ * The reducer signatures are deliberately stated over `RenderNode` /
+ * `RenderEdge` rather than sigma's `Partial<NodeDisplayData>`: those are the
+ * attributes `project.ts` actually writes, and naming sigma's types here would
+ * mean importing sigma.
+ */
+export interface SigmaLike {
+  on(event: "clickNode", handler: (payload: { node: string }) => void): unknown;
+  on(event: "clickStage", handler: () => void): unknown;
+  setSetting(key: "nodeReducer", value: (id: string, data: RenderNode) => NodeDisplayOverride): unknown;
+  setSetting(key: "edgeReducer", value: (key: string, data: RenderEdge) => EdgeDisplayOverride): unknown;
+  setGraph(graph: ProjectedGraph): unknown;
+  refresh(): unknown;
+  getCamera(): CameraLike;
+  kill(): void;
+}
+
+/**
+ * `new Sigma(graph, container, settings)`, as a port.
+ *
+ * The one line that cannot be tested, isolated behind a function type so that
+ * everything *around* it can be. `renderer.dom.ts` is the four-line adapter
+ * that supplies the real constructor.
+ */
+export type SigmaFactory = (graph: ProjectedGraph, container: RenderContainer, settings: GraphSettings) => SigmaLike;
+
+// --- the implementation --------------------------------------------------------------
+
+/**
+ * The renderer §7.5 calls `SigmaRenderer`, over an injected constructor.
+ *
+ * Holds no decisions. Colours, sizes, labels, z-order, settings and the dim
+ * rules are `graph.model.ts`; the graphology instance is `project.ts`; which
+ * nodes are highlighted is core's `focusNeighborhood`. What is left is
+ * lifecycle: build lazily, delegate, tear down once.
+ *
+ * The scheme is fixed at construction rather than settable. A
+ * `prefers-color-scheme` flip mid-session is rare enough that rebuilding the
+ * renderer is the honest response, where a `setScheme` would mean re-deriving
+ * every node colour and re-projecting — a second code path for a case nobody
+ * hits.
+ */
+export function sigmaRenderer(create: SigmaFactory, scheme: ColorScheme): GraphRenderer {
+  let sigma: SigmaLike | null = null;
+  let graph: ProjectedGraph = project({ nodes: [], edges: [] });
+  let highlight: ReadonlySet<string> | null = null;
+  let select: (id: string | null) => void = () => {};
+
+  /**
+   * Push the current highlight into sigma's reducers (§7.4).
+   *
+   * Re-installed on every change rather than reading `highlight` through a
+   * closure, because `setSetting` is what tells sigma to schedule a render —
+   * mutating a captured variable would change the answer and repaint nothing
+   * until the next unrelated frame.
+   */
+  const applyReducers = (instance: SigmaLike): void => {
+    const nodes = nodeReducer(highlight);
+    const edges = edgeReducer(highlight);
+    instance.setSetting("nodeReducer", (id, data) => ({ ...data, ...nodes(id, data, scheme) }));
+    instance.setSetting("edgeReducer", (key, data) => ({ ...data, ...edges(key, data) }));
+  };
+
+  return {
+    mount(container) {
+      if (sigma !== null) return;
+      const instance = create(graph, container, graphSettings(scheme));
+      // §1.3's context bus: a click writes `selectedId`, and the note column,
+      // the tree and the context rail all recompute from it.
+      instance.on("clickNode", ({ node }) => select(node));
+      instance.on("clickStage", () => select(null));
+      applyReducers(instance);
+      sigma = instance;
+    },
+
+    setGraph(next) {
+      graph = project(next);
+      sigma?.setGraph(graph);
+    },
+
+    setPositions(positions) {
+      syncPositions(graph, positions);
+      // `refresh` re-reads the node attributes just written; `setGraph` would
+      // rebuild every WebGL buffer and reset the camera.
+      sigma?.refresh();
+    },
+
+    setHighlight(next) {
+      highlight = next;
+      if (sigma !== null) applyReducers(sigma);
+    },
+
+    onSelect(handler) {
+      select = handler;
+    },
+
+    fit() {
+      // `animatedReset` settles when the animation ends. Nothing awaits a
+      // camera move, and a rejection from a camera killed mid-flight is noise.
+      void sigma?.getCamera().animatedReset();
+    },
+
+    positions() {
+      return positionsOf(graph);
+    },
+
+    destroy() {
+      sigma?.kill();
+      sigma = null;
+    },
+  };
+}

package/src/web/client/graph/scheme.ts

@@ -0,0 +1,44 @@
+/**
+ * Reading `prefers-color-scheme` (weave-workspace §7.4).
+ *
+ * WebGL cannot read a CSS custom property: sigma needs a concrete `#rrggbb`
+ * per node, so unlike every other column the graph has to know which palette
+ * the user is in rather than leaving it to the stylesheet. That is one media
+ * query, and it is here rather than inline in a component for §10's reason —
+ * a `matchMedia` call in a `.tsx` is a line no test can reach.
+ *
+ * The default is **dark**, matching `shell/theme.ts` (which is dark-first with
+ * a `prefers-color-scheme: light` override) rather than `page.ts`'s
+ * light-first pre-paint block. §15.1 records that disagreement as known debt;
+ * this file follows the sheet the user actually ends up looking at.
+ */
+
+import type { ColorScheme } from "./graph.model";
+
+/**
+ * The slice of `window` this module reads.
+ *
+ * `matchMedia` returns far more than `matches`, and naming `MediaQueryList`
+ * would make the module uncompilable by the root `tsconfig.json` project (no
+ * `DOM` lib), which is what a test importing it runs under. The narrow shape
+ * is the same trick `viewport.ts` and `cssvars.ts` use, and the real `window`
+ * satisfies it structurally.
+ */
+export interface SchemeHost {
+  matchMedia(query: string): { readonly matches: boolean };
+}
+
+/** The query. Light is the exception; see the module header. */
+export const LIGHT_QUERY = "(prefers-color-scheme: light)";
+
+/**
+ * Which palette to draw in.
+ *
+ * A host without `matchMedia` — an old embedding, a partial test double —
+ * gets dark rather than an exception. A graph in the wrong palette is legible;
+ * a graph that threw at mount is not.
+ */
+export function schemeOf(host: SchemeHost | null | undefined): ColorScheme {
+  if (host === null || host === undefined || typeof host.matchMedia !== "function") return "dark";
+  return host.matchMedia(LIGHT_QUERY).matches ? "light" : "dark";
+}

package/src/web/client/live.model.ts

@@ -0,0 +1,275 @@
+/**
+ * The liveness state machine, as pure data (weave-workspace §6).
+ *
+ * `src/web/server/sse.ts` pushes `{scope, stamp}` frames at the browser; this
+ * module decides two things about them, and nothing else:
+ *
+ *  1. **What must be refetched** — a {@link RefetchPlan}.
+ *  2. **What the status bar should say** — a `ConnectionState`.
+ *
+ * It is a `.model.ts` for the reason §10 gives: there is no DOM test
+ * environment in this repository and we may not add one, so every decision
+ * worth getting right lives in a pure function over plain objects and
+ * {@link ./live} is left with nothing but socket plumbing. Everything here
+ * runs under the root `tsconfig.json`, which has no `DOM` lib — hence no
+ * `EventSource`, no `MessageEvent`, and `readyState` arriving as a plain
+ * number.
+ *
+ * ## Frames are hints, not deltas
+ *
+ * §6 is explicit that macOS `fs.watch` coalesces and can drop events, so a
+ * frame means "something in this scope moved, re-read it" and never "here is
+ * what changed". That single sentence is why {@link planFor} returns *which
+ * endpoints to re-request* rather than a patch, and why there is no code here
+ * that tries to apply a frame to a graph in place. A client that treated
+ * frames as deltas would diverge silently the first time the OS dropped one,
+ * and the divergence would be invisible until someone noticed a stale node an
+ * hour later.
+ *
+ * ## Reconnect refetches everything
+ *
+ * The server keeps **no replay buffer** and ignores `Last-Event-ID` (see the
+ * `sse.ts` header). So a reopened stream carries no information about the gap,
+ * and the only correct response to "I was away for an unknown interval" is to
+ * re-request everything. That is what {@link reduceLive} produces for a
+ * reopen, and it is cheap rather than wasteful: the graph request carries
+ * `If-None-Match`, so an unchanged workspace costs one `304` with an empty
+ * body. Buffering would add retention, eviction and a resume path to arrive
+ * at the same fetch.
+ */
+
+import type { ChangeEvent, ChangeScope } from "../shared/wire";
+import { isChangeEvent } from "../shared/wire";
+import type { ConnectionState } from "./state";
+
+/** The SSE endpoint (§5.3). */
+export const EVENTS_PATH = "/events";
+
+// --- `EventSource.readyState`, without the DOM lib ------------------------------
+
+/**
+ * The three `readyState` values, restated as local constants.
+ *
+ * `EventSource.CONNECTING` and friends are DOM globals and this module is
+ * compiled by a project with no `DOM` lib, so the numbers are written down
+ * here. They are fixed by the HTML specification and cannot drift — unlike,
+ * say, an HTTP status, there is no version of the standard in which `CLOSED`
+ * stops being `2`.
+ */
+export const SOCKET_CONNECTING = 0;
+export const SOCKET_OPEN = 1;
+export const SOCKET_CLOSED = 2;
+
+// --- refetch plans ---------------------------------------------------------------
+
+/**
+ * Which endpoints a transition invalidates.
+ *
+ * Two booleans rather than a set of route names, because at P1 there are
+ * exactly two things the shell holds: the graph payload and the selected
+ * note's body. This will grow — P2 adds the `.okf` file view and the tag
+ * index — and the honest thing is to let it grow then rather than to invent a
+ * registry now for endpoints that do not exist.
+ */
+export interface RefetchPlan {
+  /** Re-request `GET /api/graph`, conditionally on the held stamp. */
+  readonly graph: boolean;
+  /** Re-request `GET /api/note/:slug` for the current selection. */
+  readonly note: boolean;
+}
+
+/** Nothing to do. Returned for a deduped frame and for an idle transition. */
+export const NO_REFETCH: RefetchPlan = { graph: false, note: false };
+
+/** Whether a plan would issue no requests at all. */
+export function isNoop(plan: RefetchPlan): boolean {
+  return !plan.graph && !plan.note;
+}
+
+/**
+ * Scope → what it can possibly have invalidated.
+ *
+ * The table is deliberately thin, and worth stating plainly rather than
+ * dressing up: **every** scope invalidates the graph, because the graph
+ * carries the vault's notes, the repository index *and* the git-state node
+ * plus its staleness report. The one real distinction is the note body — a
+ * `repo` or `git` change cannot alter the text of a note on disk, so the note
+ * column is left alone, while a `vault` change can and must re-read it.
+ *
+ * Inventing finer granularity here would be fiction. When P2 gives the client
+ * more than two things to hold, this table earns more rows.
+ *
+ * @param hasSelection whether a note is currently open in the note column;
+ *   with nothing selected there is no note to refetch.
+ */
+export function planFor(scope: ChangeScope, hasSelection: boolean): RefetchPlan {
+  return { graph: true, note: scope === "vault" && hasSelection };
+}
+
+/**
+ * The "I have been away" plan: everything the client holds.
+ *
+ * Used for a reopened stream and for the header's manual `⟳`. Both mean the
+ * same thing — the client cannot reason about what it missed — so they get
+ * the same answer rather than two subtly different ones.
+ */
+export function planForEverything(hasSelection: boolean): RefetchPlan {
+  return { graph: true, note: hasSelection };
+}
+
+// --- state --------------------------------------------------------------------------
+
+/**
+ * Everything the liveness layer remembers.
+ *
+ * `stamp` is the dedupe key and doubles as the `If-None-Match` value the
+ * shell sends. It is kept across a disconnect on purpose: a reconnect
+ * refetches everything, but it refetches *conditionally*, so holding the last
+ * known stamp turns "refetch everything" into a `304` whenever nothing
+ * actually moved while we were away.
+ */
+export interface LiveState {
+  readonly connection: ConnectionState;
+  /** Last stamp the client has applied, or `null` before the first graph. */
+  readonly stamp: string | null;
+  /**
+   * Whether the stream has ever been open.
+   *
+   * The discriminator between "first connect" and "reconnect", which is the
+   * only reason this flag exists. The first open needs no forced refetch —
+   * the shell fetches the graph on mount — while every later open does.
+   */
+  readonly opened: boolean;
+}
+
+/** Before the socket is created. Matches `state.ts`'s documented defaults. */
+export function initialLiveState(): LiveState {
+  return { connection: "live", stamp: null, opened: false };
+}
+
+/**
+ * Record a stamp the client now holds.
+ *
+ * Called by the shell after any successful graph fetch, including the one on
+ * mount. That seeding is what makes the server's hello frame free: `sse.ts`
+ * sends the current stamp to every newly attached client, and a client that
+ * already fetched that stamp at mount would otherwise treat it as news and
+ * fetch a second time.
+ *
+ * The race is still possible — the hello frame can beat the mount fetch — and
+ * it is deliberately not defended against. Losing it costs one conditional
+ * GET that answers `304`, and the machinery to prevent that would be worth
+ * more than the request it saves.
+ */
+export function withStamp(state: LiveState, stamp: string): LiveState {
+  return state.stamp === stamp ? state : { ...state, stamp };
+}
+
+// --- events -------------------------------------------------------------------------
+
+/**
+ * What can happen to the stream.
+ *
+ * `error` carries the socket's `readyState` because that is the *only* way to
+ * tell the two failures apart: `EventSource` fires the same `error` event
+ * when it is about to retry (`CONNECTING`) and when it has given up
+ * (`CLOSED`). Reading the flag is not an optimisation — without it the status
+ * bar cannot distinguish "back in a moment" from "this session is over", and
+ * would have to pick one and be wrong half the time.
+ */
+export type LiveEvent =
+  | { readonly type: "open" }
+  | { readonly type: "error"; readonly readyState: number }
+  | { readonly type: "frame"; readonly event: ChangeEvent }
+  /** The header's `⟳`. Not a socket event; refetches without touching state. */
+  | { readonly type: "refresh" }
+  /** The client closed the stream itself — navigation, or `stop()`. */
+  | { readonly type: "closed" };
+
+/** The result of one transition: the next state, and what to go and fetch. */
+export interface LiveTransition {
+  readonly state: LiveState;
+  readonly plan: RefetchPlan;
+}
+
+/**
+ * Map a socket `readyState` at the moment of an error to a status.
+ *
+ * `CLOSED` is terminal: `EventSource` only reaches it after it has stopped
+ * retrying, so `"offline"` is a statement of fact rather than a guess. Any
+ * other value means a retry is scheduled, which is `"reconnecting"`. An
+ * unrecognised number lands there too — the safe direction, because a status
+ * bar that says "reconnecting" while the client is in fact dead is a smaller
+ * lie than one that says "offline" while a retry is in flight, and the next
+ * `open` or `error` corrects it either way.
+ */
+export function connectionForError(readyState: number): ConnectionState {
+  return readyState === SOCKET_CLOSED ? "offline" : "reconnecting";
+}
+
+/**
+ * The whole liveness state machine.
+ *
+ * @param hasSelection whether the note column currently holds a note. Passed
+ *   in rather than stored, because it is owned by `selectedId` in
+ *   `state.ts` and duplicating it here would create a second copy to keep in
+ *   sync — the exact failure §1.3 avoids by having one signal.
+ */
+export function reduceLive(state: LiveState, event: LiveEvent, hasSelection: boolean): LiveTransition {
+  switch (event.type) {
+    case "open": {
+      // A reopen means an unknown gap: see the module header. The first open
+      // is not a gap — nothing preceded it — so it only flips the status.
+      const plan = state.opened ? planForEverything(hasSelection) : NO_REFETCH;
+      return { state: { ...state, connection: "live", opened: true }, plan };
+    }
+
+    case "error":
+      return { state: { ...state, connection: connectionForError(event.readyState) }, plan: NO_REFETCH };
+
+    case "frame": {
+      // The dedupe that makes the hello frame free, and that absorbs the
+      // watcher's debounce emitting two frames for one save. The stamp is a
+      // content digest of the graph payload (§5.3), so an identical stamp
+      // provably means identical content — which is what entitles this line
+      // to skip a refetch. It was `generatedAt` until §15.6, and a timestamp
+      // max does *not* carry that guarantee: an edit that did not move the
+      // maximum was discarded right here, before the conditional GET that
+      // would have caught it ever ran.
+      if (event.event.stamp === state.stamp) return { state, plan: NO_REFETCH };
+      // The stamp is *not* recorded here. It becomes ours when the refetch it
+      // triggers succeeds — recording it now would mean a failed fetch left
+      // the client believing it holds data it never received, and the next
+      // frame carrying the same stamp would be deduped away.
+      return { state: { ...state, connection: "live" }, plan: planFor(event.event.scope, hasSelection) };
+    }
+
+    case "refresh":
+      return { state, plan: planForEverything(hasSelection) };
+
+    case "closed":
+      return { state: { ...state, connection: "offline" }, plan: NO_REFETCH };
+  }
+}
+
+// --- frame decoding ------------------------------------------------------------------
+
+/**
+ * Decode one SSE `data:` line, or `null`.
+ *
+ * Total by design. This runs inside a socket callback on bytes that survived
+ * a server restart, a proxy and whatever else sits on loopback, so a
+ * malformed frame must cost a skipped refetch — never an unhandled rejection
+ * that kills the listener and silently ends liveness for the session.
+ * {@link isChangeEvent} does the structural half; this adds the `JSON.parse`
+ * that can throw.
+ */
+export function parseFrame(data: string): ChangeEvent | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  return isChangeEvent(parsed) ? parsed : null;
+}