@oxy-hq/sdk 2.6.0 → 2.9.1

package/dist/index.cjs

@@ -1,8 +1,20 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_react = require('./react-BAiiXftp.cjs');
+const require_react = require('./react-CDYGAfGA.cjs');
+let react = require("react");
+react = require_react.__toESM(react, 1);
 
 //#region src/anomalies.ts
+/** Which buckets a write may touch when the caller didn't say. Live statuses
+*  for ack/dismiss; all three for a reopen, which exists to reach dismissed
+*  ones. */
+function defaultScope(status) {
+	return status === "new" ? [
+		"new",
+		"acknowledged",
+		"dismissed"
+	] : ["new", "acknowledged"];
+}
 /**
 * Client for `/semantic/anomalies*`. Construct via `OxyClient.anomalies`
 * rather than instantiating directly — the getter wires the request helper
@@ -31,18 +43,25 @@ var AnomaliesClient = class {
 		return qs ? `?${qs}` : "";
 	}
 	/**
-	* List anomalies in the inbox, newest first.
+	* List anomalies in the inbox, ranked worst-first by event severity (active
+	* events before dismissed). Pass `order: "recent"` for latest-first.
 	*
 	* @example
 	* ```typescript
 	* // Open / unresolved anomalies only
 	* const { anomalies } = await client.anomalies.list({ status: "new" });
+	*
+	* // Second page of 25 events
+	* const page2 = await client.anomalies.list({ limit: 25, offset: 25 });
+	* console.log(`${(page2.offset ?? 25) + 1}+ of ${page2.total ?? "?"}`);
 	* ```
 	*/
 	async list(options = {}) {
 		const extra = {};
 		if (options.status) extra.status = options.status;
-		if (options.limit) extra.limit = String(options.limit);
+		if (options.limit !== void 0) extra.limit = String(options.limit);
+		if (options.offset !== void 0) extra.offset = String(options.offset);
+		if (options.order) extra.order = options.order;
 		return this.request(this.path(this.buildQuery(extra)));
 	}
 	/**
@@ -50,11 +69,20 @@ var AnomaliesClient = class {
 	* workspace, runs the detector, and upserts matching rows into the
 	* inbox. Returns counts of scanned / failed / persisted.
 	*
+	* Long-running: the server waits up to 55 s, then returns
+	* `pending: true` with zeroed counts while the scan finishes in the
+	* background. Always check `pending` before treating `0` as "nothing
+	* found", and refetch with {@link list} shortly after.
+	*
 	* @example
 	* ```typescript
 	* // Scan against a known-good reference date (matches the seed dataset)
 	* const result = await client.anomalies.scan({ as_of: "2025-12-15" });
-	* console.log(`${result.anomalies_persisted} anomalies detected`);
+	* if (result.pending) {
+	*   console.log("scan still running — refetch shortly");
+	* } else {
+	*   console.log(`${result.anomalies_persisted} anomalies detected`);
+	* }
 	* ```
 	*/
 	async scan(options = {}) {
@@ -73,15 +101,156 @@ var AnomaliesClient = class {
 		});
 	}
 	/**
+	* Update many anomalies in one request — the batch form of
+	* {@link updateStatus}. Identifiers outside the workspace are skipped rather
+	* than erroring, so `updated` (rows written) can be lower than what you sent.
+	* At most 2000 identifiers across both lists.
+	*
+	* **Prefer `eventIds`.** Inbox actions are per *event*, and a list response
+	* caps how many buckets it returns per event — so acking the bucket ids you
+	* received can leave the tail of a long chain behind, `new`, under a clean
+	* success. Naming the event lets the server write all of it. `ids` is for
+	* rows with no `event_id` (detected before events existed), which can only
+	* be named individually.
+	*
+	* `onlyStatuses` says which of an event's buckets may move. An event can span
+	* statuses, so an unbounded write resurrects buckets that were dismissed on
+	* purpose — which is why omitting it takes a scope rather than no bound at
+	* all: the live statuses (`["new", "acknowledged"]`) for an ack or dismiss,
+	* and all three for `status: "new"`, since reopening is how a dismissed
+	* anomaly comes back. The server applies that same default, so the safe
+	* behaviour does not depend on going through this client. Pass `[]` to opt
+	* out of the bound entirely.
+	*
+	* @example
+	* ```typescript
+	* const { anomalies } = await client.anomalies.list({ status: "new", limit: 50, offset: 0 });
+	* // Both lists: events by id, and pre-event rows (no `event_id`) by their own.
+	* const eventIds = [...new Set(anomalies.flatMap((a) => (a.event_id ? [a.event_id] : [])))];
+	* const ids = anomalies.filter((a) => !a.event_id).map((a) => a.id);
+	* const { updated } = await client.anomalies.updateStatusBulk(
+	*   { ids, eventIds, onlyStatuses: ["new", "acknowledged"] },
+	*   "acknowledged"
+	* );
+	* ```
+	*/
+	async updateStatusBulk(target, status) {
+		return this.request(this.path(`/status${this.buildQuery()}`), {
+			method: "POST",
+			body: JSON.stringify({
+				ids: target.ids ?? [],
+				event_ids: target.eventIds ?? [],
+				only_statuses: target.onlyStatuses ?? defaultScope(status),
+				status
+			})
+		});
+	}
+	/**
 	* Run the metric-tree `explain` for an anomaly and cache the result on
-	* the row. Subsequent calls return the cached `ExplainResult` instantly.
+	* the row. Subsequent calls return the cached `ExplainResult` instantly;
+	* pass `{ refresh: true }` to bust the cache and recompute.
+	*
+	* The uncached path runs a 20-30 s recursive driver search — budget for it
+	* (or read `explain_cache` off the row from {@link list} when it's already
+	* populated).
 	*/
-	async explain(anomalyId) {
-		const query = this.buildQuery();
-		return this.request(this.path(`/${encodeURIComponent(anomalyId)}/explain${query}`), { method: "POST" });
+	async explain(anomalyId, options = {}) {
+		const extra = {};
+		if (options.refresh) extra.refresh = "true";
+		return this.request(this.path(`/${encodeURIComponent(anomalyId)}/explain${this.buildQuery(extra)}`), { method: "POST" });
 	}
 };
 
+//#endregion
+//#region src/custom-app/base64.ts
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Reverse lookup; 255 marks "not a base64 character". */
+const B64R = /* @__PURE__ */ (() => {
+	const t = (/* @__PURE__ */ new Uint8Array(256)).fill(255);
+	for (let i = 0; i < 64; i++) t[B64.charCodeAt(i)] = i;
+	return t;
+})();
+/**
+* Chunk size for building output in segments. Byte-at-a-time `+=` allocates a
+* rope node per byte, and `String.fromCharCode.apply` blows the argument limit
+* on large inputs; 8k avoids both.
+*/
+const CHUNK = 8192;
+function asBytes(input) {
+	if (input instanceof Uint8Array) return input;
+	if (input instanceof ArrayBuffer) return new Uint8Array(input);
+	return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+}
+/**
+* Encode bytes as standard (padded) base64.
+*
+* ```ts
+* const pdf = new Uint8Array(await renderReport());
+* await ctx.email.send({
+*   to: ctx.user.email,
+*   subject: "Report",
+*   text: "attached",
+*   attachments: [{ filename: "report.pdf", content: bytesToBase64(pdf) }]
+* });
+* ```
+*
+* For **text** you generated, skip this entirely and pass the string with
+* `encoding: "utf8"` — it needs no encoder and stays byte-exact for non-ASCII.
+*/
+function bytesToBase64(input) {
+	const bytes = asBytes(input);
+	const parts = [];
+	let buf = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const b0 = bytes[i];
+		const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+		const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+		const n = b0 << 16 | b1 << 8 | b2;
+		buf += B64[n >> 18 & 63] + B64[n >> 12 & 63] + (i + 1 < bytes.length ? B64[n >> 6 & 63] : "=") + (i + 2 < bytes.length ? B64[n & 63] : "=");
+		if (buf.length >= CHUNK) {
+			parts.push(buf);
+			buf = "";
+		}
+	}
+	parts.push(buf);
+	return parts.join("");
+}
+/**
+* Decode standard base64 to bytes — e.g. the body from
+* `ctx.storage.get(key, { encoding: "base64" })`.
+*
+* Throws on malformed input rather than returning a short buffer: a truncated
+* decode that reports success is a corrupt file nobody notices.
+*/
+function base64ToBytes(base64) {
+	let s = String(base64).replace(/[ \t\n\f\r]/g, "");
+	if (s.length % 4 === 0) {
+		let pad = 0;
+		while (pad < 2 && s.charCodeAt(s.length - 1) === 61) {
+			s = s.slice(0, -1);
+			pad++;
+		}
+	}
+	if (s.indexOf("=") >= 0) throw new TypeError("base64ToBytes: '=' may only appear as trailing padding");
+	if (s.length % 4 === 1) throw new TypeError("base64ToBytes: invalid base64 length");
+	const out = new Uint8Array(s.length * 3 >> 2);
+	let o = 0;
+	let buf = 0;
+	let bits = 0;
+	for (let i = 0; i < s.length; i++) {
+		const code = s.charCodeAt(i);
+		const v = code < 256 ? B64R[code] : 255;
+		if (v === 255) throw new TypeError(`base64ToBytes: invalid base64 character '${s[i]}'`);
+		buf = buf << 6 | v;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out[o++] = buf >> bits & 255;
+		}
+	}
+	return out.subarray(0, o);
+}
+
 //#endregion
 //#region src/custom-app/debug.ts
 /**
@@ -105,6 +274,547 @@ async function getCustomAppDebug(resolved) {
 	return snapshot;
 }
 
+//#endregion
+//#region src/custom-app/metric-tree-fetch.ts
+/** Base path for the metric-tree endpoints of `projectId`. */
+function metricTreePath(projectId) {
+	return `/api/projects/${projectId}/semantic/metric-tree`;
+}
+/** GET `url`, decoding JSON or throwing a typed {@link OxyApiError}. */
+async function getJson(fetcher, url, signal) {
+	const resp = await fetcher(url, {
+		method: "GET",
+		signal
+	});
+	if (!resp.ok) throw await require_react.apiErrorFromResponse(resp);
+	return await resp.json();
+}
+/** POST `body` (tagged `v: 1`) to `url`, decoding JSON or throwing. */
+async function postJson(fetcher, url, body, signal) {
+	const resp = await fetcher(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			v: 1,
+			...body
+		}),
+		signal
+	});
+	if (!resp.ok) throw await require_react.apiErrorFromResponse(resp);
+	return await resp.json();
+}
+
+//#endregion
+//#region src/custom-app/metric-tree-hooks.tsx
+/**
+* Internal engine shared by every metric-tree hook. Runs `run(signal)`
+* whenever `key` changes (and on `refetch`), tracks loading/error, and
+* cancels in-flight work on unmount or input change.
+*
+* `key` is the deep-compare fingerprint of the request; a `null` key
+* means "no request yet" and leaves the hook idle without firing.
+*/
+function useMetricTreeEndpoint(key, run, enabled) {
+	const [data, setData] = react.useState(null);
+	const [loading, setLoading] = react.useState(enabled && key !== null);
+	const [error, setError] = react.useState(null);
+	const [_nonce, setNonce] = react.useState(0);
+	const runRef = react.useRef(run);
+	runRef.current = run;
+	react.useEffect(() => {
+		if (!enabled || key === null) {
+			setLoading(false);
+			return;
+		}
+		const ctrl = new AbortController();
+		let cancelled = false;
+		setLoading(true);
+		setError(null);
+		runRef.current(ctrl.signal).then((result) => {
+			if (cancelled) return;
+			setData(result);
+			setLoading(false);
+		}).catch((err) => {
+			if (cancelled) return;
+			if (err instanceof DOMException && err.name === "AbortError") return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+			setLoading(false);
+		});
+		return () => {
+			cancelled = true;
+			ctrl.abort();
+		};
+	}, [key, enabled]);
+	return {
+		data,
+		loading,
+		error,
+		refetch: react.useCallback(() => setNonce((n) => n + 1), [])
+	};
+}
+/**
+* The project's metric tree — measures (nodes) and their component /
+* driver relationships (edges) — or the subtree rooted at `opts.root`.
+* The structural backbone every other metric-tree analysis reads against.
+*/
+function useMetricTree(opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	const root = opts.root;
+	return useMetricTreeEndpoint(projectId ? JSON.stringify({
+		projectId,
+		root
+	}) : null, (signal) => {
+		const qs = root ? `?root=${encodeURIComponent(root)}` : "";
+		return getJson(fetcher, `${metricTreePath(projectId)}${qs}`, signal);
+	}, enabled);
+}
+/**
+* Ranked drivers of `measureId`, by influence — the "what moves this
+* measure" question. Pass `null` to stay idle until a measure is chosen.
+*/
+function useSensitivity(measureId, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId && measureId ? JSON.stringify({
+		projectId,
+		measureId
+	}) : null, (signal) => {
+		const path = `${metricTreePath(projectId)}/${encodeURIComponent(measureId)}/sensitivity`;
+		return getJson(fetcher, path, signal);
+	}, enabled);
+}
+/**
+* Propagate hypothetical `(measure, delta)` changes upward through the
+* tree and return the estimated impact on every downstream measure — a
+* pure metric-tree walk, no warehouse query. Pass `null` to stay idle.
+*/
+function usePredict(changes, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId && changes ? JSON.stringify({
+		projectId,
+		changes
+	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/predict`, { changes }, signal), enabled);
+}
+/**
+* Period-over-period root-cause decomposition: recursively splits the
+* target measure by components and dimensions until the move concentrates.
+* This is the heavy one — it can fire many warehouse queries and the
+* server caps it at 45s. Pass `null` to defer until periods are chosen.
+*/
+function useExplain(request, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId && request ? JSON.stringify({
+		projectId,
+		request
+	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/explain`, request, signal), enabled);
+}
+/**
+* Single-period distribution of a measure — an {@link ExplainResult}
+* against an auto-derived immediately-prior baseline. Same renderers as
+* `useExplain`; ignore the delta fields for a pure distribution view.
+*/
+function useDistribution(request, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId && request ? JSON.stringify({
+		projectId,
+		request
+	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/distribution`, request, signal), enabled);
+}
+/**
+* Segment opportunity sizing for a measure over a period: finds
+* underperforming segments and sizes the addressable upside of closing
+* each rate gap against a benchmark peer. Pass `null` to stay idle until
+* a target + period are chosen.
+*/
+function useOpportunity(request, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId && request ? JSON.stringify({
+		projectId,
+		request
+	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/opportunity`, request, signal), enabled);
+}
+/**
+* The queryable time dimensions per view (`view.dim` ids) — what a
+* bundle offers as the period axis for `explain` / `opportunity` /
+* `distribution` instead of hardcoding a curated map.
+*/
+function useTimeDimensions(opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId ? JSON.stringify({
+		projectId,
+		kind: "time-dimensions"
+	}) : null, (signal) => getJson(fetcher, `${metricTreePath(projectId)}/time-dimensions`, signal), enabled);
+}
+
+//#endregion
+//#region src/custom-app/sse.ts
+/**
+* Read a `text/event-stream` response, invoking `onEvent` with each parsed
+* JSON frame. Frames that fail to parse are skipped (a malformed frame must
+* not tear down the whole stream). Resolves when the body closes.
+*/
+async function readJsonSseStream(resp, onEvent) {
+	const reader = resp.body?.getReader();
+	if (!reader) throw new Error("SSE response has no body stream");
+	const decoder = new TextDecoder();
+	let buffer = "";
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let sep;
+		while ((sep = buffer.indexOf("\n\n")) !== -1) {
+			const frame = buffer.slice(0, sep);
+			buffer = buffer.slice(sep + 2);
+			let data = "";
+			for (const line of frame.split("\n")) if (line.startsWith("data:")) data += line.slice(5).trim();
+			if (!data) continue;
+			let parsed;
+			try {
+				parsed = JSON.parse(data);
+			} catch {
+				continue;
+			}
+			onEvent(parsed);
+		}
+	}
+}
+
+//#endregion
+//#region src/custom-app/world-model-hooks.tsx
+/** Base path for the world-model endpoints of the active project. */
+function worldModelPath(projectId) {
+	return `/api/projects/${projectId}/semantic/world-model`;
+}
+/**
+* The world-model graph — entities (nodes), their measures/dimensions, and
+* how measures promote across the entity hierarchy (edges). Applies the
+* project's `.world-model.yml` display config server-side.
+*
+* @remarks
+* This returns the raw semantic-layer entity graph. For the higher-level
+* node-paradigm interface (`world.metric(id)` speaking `expand` / `explain` /
+* `size`), use {@link useWorldModel} from `./world-node` instead.
+*/
+function useWorldModelGraph(opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	const [data, setData] = react.useState(null);
+	const [loading, setLoading] = react.useState(enabled && !!projectId);
+	const [error, setError] = react.useState(null);
+	const [_nonce, setNonce] = react.useState(0);
+	react.useEffect(() => {
+		if (!enabled || !projectId) {
+			setLoading(false);
+			return;
+		}
+		const ctrl = new AbortController();
+		let cancelled = false;
+		setLoading(true);
+		setError(null);
+		fetcher(worldModelPath(projectId), {
+			method: "GET",
+			signal: ctrl.signal
+		}).then(async (resp) => {
+			if (!resp.ok) throw await require_react.apiErrorFromResponse(resp);
+			return await resp.json();
+		}).then((result) => {
+			if (cancelled) return;
+			setData(result);
+			setLoading(false);
+		}).catch((err) => {
+			if (cancelled) return;
+			if (err instanceof DOMException && err.name === "AbortError") return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+			setLoading(false);
+		});
+		return () => {
+			cancelled = true;
+			ctrl.abort();
+		};
+	}, [
+		enabled,
+		projectId,
+		fetcher
+	]);
+	return {
+		data,
+		loading,
+		error,
+		refetch: react.useCallback(() => setNonce((n) => n + 1), [])
+	};
+}
+/**
+* List the instances (rows) of `entityId` — a bounded, searchable picker
+* over the entity's primary keys + display label. Pass `null` for `entityId`
+* to stay idle until an entity is chosen.
+*/
+function useWorldModelInstances(entityId, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	const { search, limit } = opts;
+	const [data, setData] = react.useState(null);
+	const [loading, setLoading] = react.useState(enabled && !!projectId && !!entityId);
+	const [error, setError] = react.useState(null);
+	const [_nonce, setNonce] = react.useState(0);
+	react.useEffect(() => {
+		if (!enabled || !projectId || !entityId) {
+			setLoading(false);
+			return;
+		}
+		const ctrl = new AbortController();
+		let cancelled = false;
+		setLoading(true);
+		setError(null);
+		const params = new URLSearchParams({ entity: entityId });
+		if (search) params.set("search", search);
+		if (limit != null) params.set("limit", String(limit));
+		fetcher(`${worldModelPath(projectId)}/instances?${params}`, {
+			method: "GET",
+			signal: ctrl.signal
+		}).then(async (resp) => {
+			if (!resp.ok) throw await require_react.apiErrorFromResponse(resp);
+			return await resp.json();
+		}).then((result) => {
+			if (cancelled) return;
+			setData(result);
+			setLoading(false);
+		}).catch((err) => {
+			if (cancelled) return;
+			if (err instanceof DOMException && err.name === "AbortError") return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+			setLoading(false);
+		});
+		return () => {
+			cancelled = true;
+			ctrl.abort();
+		};
+	}, [
+		enabled,
+		projectId,
+		entityId,
+		search,
+		limit,
+		fetcher
+	]);
+	return {
+		data,
+		loading,
+		error,
+		refetch: react.useCallback(() => setNonce((n) => n + 1), [])
+	};
+}
+/** Fold one measure-breakdown SSE frame into the accumulated graph. */
+function foldBreakdown(prev, ev) {
+	switch (ev.kind) {
+		case "init": return {
+			root: ev.root,
+			nodes: ev.nodes.map((n) => ({
+				...n,
+				value: null,
+				unvalued_reason: null
+			})),
+			edges: ev.edges
+		};
+		case "value":
+			if (!prev) return prev;
+			return {
+				...prev,
+				nodes: prev.nodes.map((n) => n.id === ev.node_id ? {
+					...n,
+					value: ev.value,
+					unvalued_reason: ev.unvalued_reason
+				} : n)
+			};
+		default: return prev;
+	}
+}
+/**
+* Stream the driver-tree breakdown of one instance's measure — the metric
+* decomposition (add/sub/mul/div component graph) with each node's value
+* filling in as it resolves. This is the per-instance RCA view. Pass `null`
+* for `measure` to stay idle.
+*/
+function useMeasureBreakdown(entityId, keyValue, measure) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const [breakdown, setBreakdown] = react.useState(null);
+	const [loading, setLoading] = react.useState(false);
+	const [done, setDone] = react.useState(false);
+	const [error, setError] = react.useState(null);
+	react.useEffect(() => {
+		if (!projectId || !entityId || !keyValue || !measure) {
+			setLoading(false);
+			return;
+		}
+		const ctrl = new AbortController();
+		let cancelled = false;
+		setBreakdown(null);
+		setLoading(true);
+		setDone(false);
+		setError(null);
+		const params = new URLSearchParams({
+			entity: entityId,
+			key: keyValue,
+			measure
+		});
+		fetcher(`${worldModelPath(projectId)}/measure-breakdown?${params}`, {
+			method: "GET",
+			signal: ctrl.signal
+		}).then(async (resp) => {
+			if (!resp.ok) throw await require_react.apiErrorFromResponse(resp);
+			await readJsonSseStream(resp, (ev) => {
+				if (cancelled) return;
+				if (ev.kind === "done") {
+					setDone(true);
+					return;
+				}
+				setBreakdown((prev) => foldBreakdown(prev, ev));
+			});
+			if (!cancelled) setLoading(false);
+		}).catch((err) => {
+			if (cancelled) return;
+			if (err instanceof DOMException && err.name === "AbortError") return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+			setLoading(false);
+		});
+		return () => {
+			cancelled = true;
+			ctrl.abort();
+		};
+	}, [
+		projectId,
+		entityId,
+		keyValue,
+		measure,
+		fetcher
+	]);
+	return {
+		breakdown,
+		loading,
+		done,
+		error
+	};
+}
+
+//#endregion
+//#region src/custom-app/world-node.tsx
+/**
+* Thrown by the value verbs (`explain` / `size`) when called on a handle that
+* has been `drill`ed. The metric-tree backend cannot yet scope these analyses
+* to a segment, so failing loud beats returning population numbers for a
+* question that asked about one segment.
+*/
+var WorldModelScopeUnsupportedError = class extends Error {
+	constructor(verb, scope) {
+		super(`${verb} on a drilled (scoped) node is not yet supported by the backend (scope: ${JSON.stringify(scope)}). Call ${verb} on the un-drilled node for population-level analysis.`);
+		this.code = "world_model_scope_unsupported";
+		this.name = "WorldModelScopeUnsupportedError";
+		this.scope = scope;
+	}
+};
+/**
+* Build a {@link WorldModelApi} over a project id and fetcher. Framework-
+* agnostic — `useWorldModel()` wraps this for React, but it is directly
+* unit-testable with a mock fetcher.
+*/
+function createWorldModel(projectId, fetcher) {
+	const base = () => {
+		if (!projectId) throw new Error("World Model unavailable: no active project (are you inside <OxyAppProvider>?)");
+		return metricTreePath(projectId);
+	};
+	const tree = (root, signal) => {
+		const qs = root ? `?root=${encodeURIComponent(root)}` : "";
+		return getJson(fetcher, `${base()}${qs}`, signal);
+	};
+	const makeHandle = (id, scope) => {
+		const scoped = Object.keys(scope).length > 0;
+		return {
+			id,
+			scope,
+			async node(signal) {
+				const found = (await tree(id, signal)).nodes.find((n) => n.id === id);
+				if (!found) throw new Error(`measure '${id}' not found in the metric tree`);
+				return found;
+			},
+			async expand(signal) {
+				const t = await tree(id, signal);
+				const byId = new Map(t.nodes.map((n) => [n.id, n]));
+				const children = [];
+				for (const edge of t.edges) {
+					if (edge.from !== id) continue;
+					const childNode = byId.get(edge.to);
+					if (!childNode) continue;
+					children.push({
+						node: childNode,
+						edge,
+						handle: makeHandle(edge.to, scope)
+					});
+				}
+				return children;
+			},
+			drivers(signal) {
+				return getJson(fetcher, `${base()}/${encodeURIComponent(id)}/sensitivity`, signal);
+			},
+			explain(opts, signal) {
+				if (scoped) throw new WorldModelScopeUnsupportedError("explain", scope);
+				return postJson(fetcher, `${base()}/explain`, {
+					target: id,
+					...opts
+				}, signal);
+			},
+			size(opts, signal) {
+				if (scoped) throw new WorldModelScopeUnsupportedError("size", scope);
+				return postJson(fetcher, `${base()}/opportunity`, {
+					target: id,
+					...opts
+				}, signal);
+			},
+			drill(next) {
+				return makeHandle(id, {
+					...scope,
+					...next
+				});
+			}
+		};
+	};
+	return {
+		projectId,
+		tree,
+		metric: (id) => makeHandle(id, {})
+	};
+}
+/**
+* The World Model node interface, scoped to the active `<OxyAppProvider>`
+* project. Returns a stable {@link WorldModelApi} — grab a node with
+* `world.metric(id)` and let it speak the verbs.
+*
+* @example
+* ```tsx
+* const world = useWorldModel();
+* const revenue = world.metric("orders.net_revenue");
+* const children = await revenue.expand();       // components + drivers
+* const rca = await revenue.explain({
+*   time_dimension: "orders.order_date",
+*   current_period: ["2026-06-01", "2026-06-30"],
+*   previous_period: ["2026-05-01", "2026-05-31"],
+* });
+* ```
+*
+* @remarks
+* This is the node-paradigm hook. For the raw semantic-layer entity/measure
+* graph, use {@link useWorldModelGraph} instead.
+*/
+function useWorldModel() {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	return react.useMemo(() => createWorldModel(projectId ?? null, fetcher), [projectId, fetcher]);
+}
+
 //#endregion
 //#region src/metricTree.ts
 /**
@@ -240,20 +950,36 @@ exports.OxyAnswer = require_react.OxyAnswer;
 exports.OxyApiError = require_react.OxyApiError;
 exports.OxyAppProvider = require_react.OxyAppProvider;
 exports.OxyChat = require_react.OxyChat;
+exports.WorldModelScopeUnsupportedError = WorldModelScopeUnsupportedError;
 exports._resetCustomAppManifestCacheForTest = require_react._resetCustomAppManifestCacheForTest;
 exports.apiErrorFromResponse = require_react.apiErrorFromResponse;
+exports.base64ToBytes = base64ToBytes;
+exports.bytesToBase64 = bytesToBase64;
+exports.createWorldModel = createWorldModel;
 exports.getCustomAppDebug = getCustomAppDebug;
 exports.getOxyAppLogger = require_react.getOxyAppLogger;
 exports.interpretCustomAppError = require_react.interpretCustomAppError;
 exports.loadCustomAppManifest = require_react.loadCustomAppManifest;
 exports.readInjectedAppConfig = require_react.readInjectedAppConfig;
+exports.readJsonSseStream = readJsonSseStream;
 exports.setOxyAppLogger = require_react.setOxyAppLogger;
 exports.useAgentRun = require_react.useAgentRun;
+exports.useDistribution = useDistribution;
+exports.useExplain = useExplain;
 exports.useFunction = require_react.useFunction;
+exports.useMeasureBreakdown = useMeasureBreakdown;
+exports.useMetricTree = useMetricTree;
+exports.useOpportunity = useOpportunity;
 exports.useOxyApp = require_react.useOxyApp;
+exports.usePredict = usePredict;
 exports.useProcedureRun = require_react.useProcedureRun;
 exports.useQuery = require_react.useQuery;
 exports.useResolvedManifest = require_react.useResolvedManifest;
 exports.useSemanticQuery = require_react.useSemanticQuery;
+exports.useSensitivity = useSensitivity;
+exports.useTimeDimensions = useTimeDimensions;
 exports.useTrackEvent = require_react.useTrackEvent;
+exports.useWorldModel = useWorldModel;
+exports.useWorldModelGraph = useWorldModelGraph;
+exports.useWorldModelInstances = useWorldModelInstances;
 //# sourceMappingURL=index.cjs.map