Custom Global Events

Overview

Global events are used for cross-component communication without React context dependencies, allowing for simple function calls to trigger events across different parts of the application.

Global Events Guidelines

Global events are used for cross-component communication without React context dependencies, allowing for simple function calls to trigger events across different parts of the application.

Overview

The global events system lives at global-event.tsx and is built on a typed Event subclass (XCustomEvent).

It exposes:

• global_event_Event: the canonical type map of event keys → detail payload types
• global_event_dispatch(event, payload): dispatch a typed event (works outside React)
• global_event_listen(event, handler, options?): listen with typed handler (works outside React)
• useGlobalEvent(event, handler): React hook for subscriptions with stale-closure protection

Event key naming

Event keys are string literals using the pattern:

(module::event_name), for example ai_chat::open_canvas.

How to add or modify an event

When the user requests a new global event, you must:

Update the event map

Add the new event key to the global_event_Event map in global-event.tsx.

Example:

export class global_event_Event extends XCustomEvent<{
	"ai_chat::open_canvas": {
		pageId: app_convex_Id<"pages">;
		mode: "diff" | "editor";
		modifiedContent?: string;
		threadId: string;
	};
	"ai_chat::open_canvas_by_path": {
		path: string;
	};
	"docs::focus_path": {
		path: string;
	};
}> {}

Keep all event keys centralized

All supported global event keys must be declared in that global_event_Event type map. Do not introduce ad-hoc stringly-typed events elsewhere.

Use the exported helpers

Prefer global_event_dispatch / global_event_listen / useGlobalEvent rather than calling window.dispatchEvent(new CustomEvent(...)) directly.

Usage patterns

React components

Use useGlobalEvent(eventName, handler) to subscribe. The handler receives a typed event object, and the payload is on event.detail.

Example (from canvas.tsx):

useGlobalEvent("ai_chat::open_canvas", (e) => {
	const payload = e.detail;
	// payload.pageId, payload.mode, payload.modifiedContent, payload.threadId
});

Non-React code (or manual lifecycle control)

Use global_event_listen directly when you need to wire AbortController, or you are outside React.

const controller = new AbortController();

const cleanup = global_event_listen(
	"ai_chat::open_canvas_by_path",
	(e) => {
		console.info("path:", e.detail.path);
	},
	{ signal: controller.signal },
);

// later:
controller.abort();
cleanup();

Dispatching

Use global_event_dispatch(eventName, payload) from anywhere client-side.

Example (from app-ai-chat.tsx):

global_event_dispatch("ai_chat::open_canvas_by_path", { path: args.path });

Handler typing and payload access

Handlers receive the typed event object, not the payload directly:

useGlobalEvent("ai_chat::open_canvas", (e) => {
	const payload = e.detail;
});

Files and references

• Core implementation: global-event.tsx
• Typed event base: XCustomEvent in utils.ts
• Hook helper: useLiveRef in utils-hooks.ts
• Example consumers: app-ai-chat.tsx, canvas.tsx