@oxy-hq/sdk 1.0.0 → 2.0.1

package/dist/index.mjs

@@ -1,1068 +1,1651 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
-import { a as PostMessageAuthInvalidResponseError, i as PostMessageAuthInvalidOriginError, o as PostMessageAuthNotInIframeError, r as requestAuthFromParent, s as PostMessageAuthTimeoutError, t as isInIframe } from "./postMessage-Gnhr_wnw.mjs";
-import * as duckdb from "@duckdb/duckdb-wasm";
-import React, { createContext, useContext, useEffect, useState } from "react";
+import * as React from "react";
 
-//#region src/config.ts
-/**
-* Safely get environment variable in both Node.js and browser environments
-*/
-function getEnvVar(name) {
-	if (typeof process !== "undefined" && process.env) return process.env[name];
-	if (typeof import.meta !== "undefined" && import.meta.env) {
-		const viteValue = import.meta.env[`VITE_${name}`];
-		if (viteValue !== void 0) return viteValue;
-		return import.meta.env[name];
-	}
+//#region src/customer-app/logger.ts
+let activeLogger = createConsoleLogger();
+/** Replace the global logger. Pass `null` to silence everything. */
+function setOxyAppLogger(logger) {
+	activeLogger = logger ?? silentLogger();
 }
-/**
-* Creates an Oxy configuration from environment variables
-*
-* Environment variables:
-* - OXY_URL: Base URL of the Oxy API
-* - OXY_API_KEY: API key for authentication
-* - OXY_PROJECT_ID: Project ID (UUID)
-* - OXY_BRANCH: (Optional) Branch name
-*
-* @param overrides - Optional configuration overrides
-* @returns OxyConfig object
-* @throws Error if required environment variables are missing
-*/
-function createConfig(overrides) {
-	const baseUrl = overrides?.baseUrl || getEnvVar("OXY_URL");
-	const apiKey = overrides?.apiKey || getEnvVar("OXY_API_KEY");
-	const projectId = overrides?.projectId || getEnvVar("OXY_PROJECT_ID");
-	if (!baseUrl) throw new Error("OXY_URL environment variable or baseUrl config is required");
-	if (!projectId) throw new Error("OXY_PROJECT_ID environment variable or projectId config is required");
-	return {
-		baseUrl: baseUrl.replace(/\/$/, ""),
-		apiKey,
-		projectId,
-		branch: overrides?.branch || getEnvVar("OXY_BRANCH"),
-		timeout: overrides?.timeout || 3e4,
-		parentOrigin: overrides?.parentOrigin,
-		disableAutoAuth: overrides?.disableAutoAuth
-	};
+/** Used by the SDK internals; not part of the public surface. */
+function getOxyAppLogger() {
+	return activeLogger;
+}
+function createConsoleLogger() {
+	return { log(level, msg, ctx) {
+		if (typeof console === "undefined") return;
+		const prefix = "[oxy-app]";
+		const args = ctx ? [
+			prefix,
+			msg,
+			ctx
+		] : [prefix, msg];
+		switch (level) {
+			case "debug":
+				console.debug(...args);
+				break;
+			case "info":
+				console.info(...args);
+				break;
+			case "warn":
+				console.warn(...args);
+				break;
+			case "error":
+				console.error(...args);
+				break;
+		}
+	} };
+}
+function silentLogger() {
+	return { log() {} };
 }
+
+//#endregion
+//#region src/customer-app/debug.ts
 /**
-* Creates an Oxy configuration asynchronously with support for postMessage authentication
-*
-* This is the recommended method for iframe scenarios where authentication
-* needs to be obtained from the parent window via postMessage.
-*
-* When running in an iframe without an API key, this function will:
-* 1. Detect the iframe context
-* 2. Send an authentication request to the parent window
-* 3. Wait for the parent to respond with credentials
-* 4. Return the configured client
-*
-* Environment variables (fallback):
-* - OXY_URL: Base URL of the Oxy API
-* - OXY_API_KEY: API key for authentication
-* - OXY_PROJECT_ID: Project ID (UUID)
-* - OXY_BRANCH: (Optional) Branch name
-*
-* @param overrides - Optional configuration overrides
-* @returns Promise resolving to OxyConfig object
-* @throws Error if required configuration is missing
-* @throws PostMessageAuthTimeoutError if parent doesn't respond
-*
-* @example
-* ```typescript
-* // Automatic iframe detection and authentication
-* const config = await createConfigAsync({
-*   parentOrigin: 'https://app.example.com',
-*   projectId: 'my-project-id',
-*   baseUrl: 'https://api.oxy.tech'
-* });
-* ```
+* Fetch the server-side diagnostic snapshot for this bundle. Pair with
+* `loadCustomerAppManifest()` — pass its result here. Logs the
+* snapshot through the SDK logger so it appears in the bundle's
+* console at info level.
 */
-async function createConfigAsync(overrides) {
-	const { isInIframe } = await import("./postMessage-Gnhr_wnw.mjs").then((n) => n.n);
-	let baseUrl = overrides?.baseUrl || getEnvVar("OXY_URL");
-	let apiKey = overrides?.apiKey || getEnvVar("OXY_API_KEY");
-	let projectId = overrides?.projectId || getEnvVar("OXY_PROJECT_ID");
-	const disableAutoAuth = overrides?.disableAutoAuth ?? false;
-	const parentOrigin = overrides?.parentOrigin || (window?.location.ancestorOrigins?.[0] ? window.location.ancestorOrigins[0] : "https://app.oxy.tech");
-	if (!disableAutoAuth && isInIframe() && !apiKey) if (!parentOrigin) logWarningAboutMissingParentOrigin();
-	else apiKey = await attemptPostMessageAuth(parentOrigin, overrides?.timeout || 5e3, apiKey, projectId, baseUrl).then((result) => {
-		if (result.projectId) projectId = result.projectId;
-		if (result.baseUrl) baseUrl = result.baseUrl;
-		return result.apiKey;
-	}).catch((error) => {
-		console.error("[Oxy SDK] Failed to authenticate via postMessage:", error.message);
-		return apiKey;
-	});
-	return createFinalConfig(baseUrl, apiKey, projectId, overrides);
-}
-function logWarningAboutMissingParentOrigin() {
-	console.warn("[Oxy SDK] Running in iframe without API key and no parentOrigin specified. PostMessage authentication will be skipped. Provide parentOrigin config to enable automatic authentication.");
+async function getCustomerAppDebug(resolved) {
+	const log = getOxyAppLogger();
+	const { apiBaseUrl, orgSlug, appSlug } = resolved;
+	const url = `${apiBaseUrl}/api/customer-apps/${encodeURIComponent(orgSlug)}/${encodeURIComponent(appSlug)}/debug`;
+	log.log("debug", "fetching debug snapshot", { url });
+	const res = await fetch(url, { credentials: "same-origin" });
+	if (!res.ok) {
+		const detail = await res.text().catch(() => "");
+		throw new Error(`Failed to fetch debug snapshot (HTTP ${res.status}): ${detail || res.statusText}`);
+	}
+	const snapshot = await res.json();
+	log.log("info", "debug snapshot", snapshot);
+	return snapshot;
 }
-async function attemptPostMessageAuth(parentOrigin, timeout, currentApiKey, currentProjectId, currentBaseUrl) {
-	const { requestAuthFromParent } = await import("./postMessage-Gnhr_wnw.mjs").then((n) => n.n);
-	const authResult = await requestAuthFromParent({
-		parentOrigin,
-		timeout
-	});
-	console.log("[Oxy SDK] Successfully authenticated via postMessage");
-	return {
-		apiKey: authResult.apiKey || currentApiKey,
-		projectId: authResult.projectId || currentProjectId,
-		baseUrl: authResult.baseUrl || currentBaseUrl
+
+//#endregion
+//#region src/customer-app/errors.ts
+const ARCH_DOC = "internal-docs/customer-apps.md";
+/** Interpret a thrown error as a structured report for UI display. */
+function interpretCustomerAppError(err) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (/Failed to load oxy-app\.json.*HTTP 404/.test(message)) return {
+		title: "Manifest not found",
+		message,
+		hint: "The bundle is being served, but oxy-app.json was not. Check that public/oxy-app.json is committed in the customer-app repo and that the build copied it into the static output. If you're using Next.js, anything under public/ is auto-copied to out/.",
+		docs: ARCH_DOC
+	};
+	if (/Failed to load oxy-app\.json/.test(message)) return {
+		title: "Manifest could not be loaded",
+		message,
+		hint: "Network error fetching the manifest. Confirm the bundle is being served from a path that matches OXY_APP_BASE_PATH at build time — a mismatch causes assets and the manifest to 404.",
+		docs: ARCH_DOC
+	};
+	if (/schemaVersion/i.test(message)) return {
+		title: "Manifest schema mismatch",
+		message,
+		hint: "This bundle was built against a different version of the data-product contract than the SDK it ships. Rebuild the bundle with a compatible @oxy-hq/sdk version.",
+		docs: ARCH_DOC
+	};
+	if (/^401:/m.test(message)) return {
+		title: "Session expired",
+		message,
+		hint: "Reload the page to re-authenticate via oxy's session cookie.",
+		docs: ARCH_DOC
+	};
+	if (/^403:.*origin not allowed/im.test(message)) return {
+		title: "Request origin not allowed",
+		message,
+		hint: "The bundle's host isn't in oxy's OXY_ALLOWED_ORIGINS. Production: add the bundle's serving origin to the env var. Local dev: oxy auto-allows http://localhost:5173 and :5174.",
+		docs: ARCH_DOC
+	};
+	if (/^403:.*not a member/im.test(message)) return {
+		title: "Access denied",
+		message,
+		hint: "Your account isn't a member of the org that owns this project. Ask an org owner to add you.",
+		docs: ARCH_DOC
+	};
+	if (/^403:.*SELECT.*WITH/im.test(message)) return {
+		title: "Query rejected — read-only endpoint",
+		message,
+		hint: "This proxy only runs SELECT or WITH queries. Mutations (INSERT/UPDATE/DELETE/DROP) are not allowed from customer-app bundles.",
+		docs: ARCH_DOC
+	};
+	if (/^403:/m.test(message)) return {
+		title: "Access denied",
+		message,
+		hint: "The request was rejected by the server. Check the oxy server logs for details.",
+		docs: ARCH_DOC
+	};
+	if (/^404:/m.test(message) && /project/i.test(message)) return {
+		title: "Project not found",
+		message,
+		hint: "The projectId in oxy-app.json doesn't match any registered project. Confirm the manifest's projectId is a real UUID for this deployment.",
+		docs: ARCH_DOC
+	};
+	if (/^400:.*sql.*must be non-empty/im.test(message)) return {
+		title: "Empty SQL",
+		message,
+		hint: "useQuery was called with an empty or whitespace-only `sql`. Pass a real query, or set `enabled: false` to skip the call.",
+		docs: ARCH_DOC
+	};
+	if (/^400:/m.test(message) && /query failed/i.test(message)) return {
+		title: "Query failed",
+		message,
+		hint: "The SQL ran but the warehouse rejected it. Full error in the oxy server logs (look for the projects::query span).",
+		docs: ARCH_DOC
+	};
+	if (/^502:/m.test(message)) return {
+		title: "Warehouse unreachable",
+		message,
+		hint: "Oxy couldn't reach the configured database. Check connector config + warehouse health.",
+		docs: ARCH_DOC
+	};
+	if (/Unexpected token '<'|<!doctype/i.test(message)) return {
+		title: "Fetched HTML where JSON was expected",
+		message,
+		hint: "Most likely the built bundle is stale — built against an old SDK whose endpoints no longer exist on the server. Rebuild the bundle (vite build) with @oxy-hq/sdk@^2.0.0 and reload. If the bundle is current, check that OXY_APP_BASE_PATH matches the path the customer-app row is served at.",
+		docs: ARCH_DOC
 	};
-}
-function createFinalConfig(baseUrl, apiKey, projectId, overrides) {
-	if (!baseUrl) throw new Error("OXY_URL environment variable or baseUrl config is required");
-	if (!projectId) throw new Error("OXY_PROJECT_ID environment variable or projectId config is required");
 	return {
-		baseUrl: baseUrl.replace(/\/$/, ""),
-		apiKey,
-		projectId,
-		branch: overrides?.branch || getEnvVar("OXY_BRANCH"),
-		timeout: overrides?.timeout || 3e4,
-		parentOrigin: overrides?.parentOrigin,
-		disableAutoAuth: overrides?.disableAutoAuth
+		title: "Unexpected error loading the dashboard",
+		message,
+		hint: "Check the browser console for the full stack trace, and the oxy server logs for the corresponding request.",
+		docs: ARCH_DOC
 	};
 }
 
 //#endregion
-//#region src/parquet.ts
-let dbInstance = null;
-let connection = null;
-let operationQueue = Promise.resolve();
+//#region src/customer-app/inject.ts
 /**
-* Enqueue an operation to prevent race conditions on shared DuckDB instance
+* Read the runtime app-config oxy injected at serve time. Returns
+* `undefined` outside the browser or when the global isn't set
+* (`pnpm dev` against a non-oxy server, etc. — manifest hints are
+* the fallback).
 */
-function enqueueOperation(operation) {
-	const currentOperation = operationQueue.then(operation, operation);
-	operationQueue = currentOperation.then(() => {}, () => {});
-	return currentOperation;
+function readInjectedAppConfig() {
+	if (typeof window === "undefined") return void 0;
+	return window.__OXY_APP__;
 }
+
+//#endregion
+//#region src/customer-app/manifest.ts
+let cached = null;
 /**
-* Initialize DuckDB-WASM instance
+* Load + validate the manifest. Cached after the first call so callers
+* can invoke this from every component without coordinating.
 */
-async function initializeDuckDB() {
-	if (dbInstance) return dbInstance;
-	const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();
-	const bundle = await duckdb.selectBundle(JSDELIVR_BUNDLES);
-	const worker_url = URL.createObjectURL(new Blob([`importScripts("${bundle.mainWorker}");`], { type: "text/javascript" }));
-	const worker = new Worker(worker_url);
-	const logger = new duckdb.ConsoleLogger();
-	dbInstance = new duckdb.AsyncDuckDB(logger, worker);
-	await dbInstance.instantiate(bundle.mainModule, bundle.pthreadWorker);
-	URL.revokeObjectURL(worker_url);
-	return dbInstance;
+function loadCustomerAppManifest(options = {}) {
+	if (!cached) cached = fetchAndValidate(options);
+	return cached;
 }
-/**
-* Get or create a DuckDB connection
-*/
-async function getConnection() {
-	if (connection) return connection;
-	connection = await (await initializeDuckDB()).connect();
-	return connection;
+/** For tests: reset the cache between runs. */
+function _resetCustomerAppManifestCacheForTest() {
+	cached = null;
 }
-/**
-* ParquetReader provides methods to read and query Parquet files.
-* Supports registering multiple Parquet files with different table names.
-*/
-var ParquetReader = class {
-	constructor() {
-		this.tableMap = /* @__PURE__ */ new Map();
-	}
-	/**
-	* Generate a unique internal table name to prevent conflicts
-	*/
-	generateInternalTableName(tableName) {
-		return `${tableName}_${`${Date.now()}_${Math.random().toString(36).substring(2, 9)}`}`;
-	}
-	/**
-	* Register a Parquet file from a Blob with a specific table name
-	*
-	* @param blob - Parquet file as Blob
-	* @param tableName - Name to use for the table in queries (required)
-	*
-	* @example
-	* ```typescript
-	* const blob = await client.getFile('data/sales.parquet');
-	* const reader = new ParquetReader();
-	* await reader.registerParquet(blob, 'sales');
-	* ```
-	*
-	* @example
-	* ```typescript
-	* // Register multiple files
-	* const reader = new ParquetReader();
-	* await reader.registerParquet(salesBlob, 'sales');
-	* await reader.registerParquet(customersBlob, 'customers');
-	* const result = await reader.query('SELECT * FROM sales JOIN customers ON sales.customer_id = customers.id');
-	* ```
-	*/
-	async registerParquet(blob, tableName) {
-		const internalTableName = this.generateInternalTableName(tableName);
-		await enqueueOperation(async () => {
-			const conn = await getConnection();
-			const db = await initializeDuckDB();
-			const arrayBuffer = await blob.arrayBuffer();
-			const uint8Array = new Uint8Array(arrayBuffer);
-			await db.registerFileBuffer(`${internalTableName}.parquet`, uint8Array);
-			try {
-				await conn.query(`DROP TABLE IF EXISTS ${internalTableName}`);
-			} catch {}
-			await conn.query(`CREATE TABLE ${internalTableName} AS SELECT * FROM '${internalTableName}.parquet'`);
-			this.tableMap.set(tableName, internalTableName);
-		});
-	}
-	/**
-	* Register multiple Parquet files at once
-	*
-	* @param files - Array of objects containing blob and tableName
-	*
-	* @example
-	* ```typescript
-	* const reader = new ParquetReader();
-	* await reader.registerMultipleParquet([
-	*   { blob: salesBlob, tableName: 'sales' },
-	*   { blob: customersBlob, tableName: 'customers' },
-	*   { blob: productsBlob, tableName: 'products' }
-	* ]);
-	* const result = await reader.query('SELECT * FROM sales JOIN customers ON sales.customer_id = customers.id');
-	* ```
-	*/
-	async registerMultipleParquet(files) {
-		for (const file of files) await this.registerParquet(file.blob, file.tableName);
-	}
-	/**
-	* Execute a SQL query against the registered Parquet data
-	*
-	* @param sql - SQL query string
-	* @returns Query result with columns and rows
-	*
-	* @example
-	* ```typescript
-	* const result = await reader.query('SELECT * FROM sales LIMIT 10');
-	* console.log(result.columns);
-	* console.log(result.rows);
-	* ```
-	*
-	* @example
-	* ```typescript
-	* // Query multiple tables
-	* await reader.registerParquet(salesBlob, 'sales');
-	* await reader.registerParquet(customersBlob, 'customers');
-	* const result = await reader.query(`
-	*   SELECT s.*, c.name
-	*   FROM sales s
-	*   JOIN customers c ON s.customer_id = c.id
-	* `);
-	* ```
-	*/
-	async query(sql) {
-		if (this.tableMap.size === 0) throw new Error("No Parquet files registered. Call registerParquet() first.");
-		return enqueueOperation(async () => {
-			const conn = await getConnection();
-			let rewrittenSql = sql;
-			for (const [userTableName, internalTableName] of this.tableMap.entries()) rewrittenSql = rewrittenSql.replace(new RegExp(`\\b${userTableName}\\b`, "g"), internalTableName);
-			const result = await conn.query(rewrittenSql);
-			const columns = result.schema.fields.map((field) => field.name);
-			const rows = [];
-			for (let i = 0; i < result.numRows; i++) {
-				const row = [];
-				for (let j = 0; j < result.numCols; j++) {
-					const col = result.getChildAt(j);
-					row.push(col?.get(i));
-				}
-				rows.push(row);
-			}
-			return {
-				columns,
-				rows,
-				rowCount: result.numRows
-			};
-		});
-	}
-	/**
-	* Get all data from a registered table
-	*
-	* @param tableName - Name of the table to query
-	* @param limit - Maximum number of rows to return (default: all)
-	* @returns Query result
-	*
-	* @example
-	* ```typescript
-	* const allData = await reader.getAll('sales');
-	* const first100 = await reader.getAll('sales', 100);
-	* ```
-	*/
-	async getAll(tableName, limit) {
-		const limitClause = limit ? ` LIMIT ${limit}` : "";
-		return this.query(`SELECT * FROM ${tableName}${limitClause}`);
-	}
-	/**
-	* Get table schema information
-	*
-	* @param tableName - Name of the table to describe
-	* @returns Schema information
-	*
-	* @example
-	* ```typescript
-	* const schema = await reader.getSchema('sales');
-	* console.log(schema.columns); // ['id', 'name', 'sales']
-	* console.log(schema.rows);    // [['id', 'INTEGER'], ['name', 'VARCHAR'], ...]
-	* ```
-	*/
-	async getSchema(tableName) {
-		return this.query(`DESCRIBE ${tableName}`);
-	}
-	/**
-	* Get row count for a table
-	*
-	* @param tableName - Name of the table to count
-	* @returns Number of rows in the table
-	*
-	* @example
-	* ```typescript
-	* const count = await reader.count('sales');
-	* console.log(`Total rows: ${count}`);
-	* ```
-	*/
-	async count(tableName) {
-		return (await this.query(`SELECT COUNT(*) as count FROM ${tableName}`)).rows[0][0];
-	}
-	/**
-	* Close and cleanup all registered resources
-	*/
-	async close() {
-		if (this.tableMap.size > 0) await enqueueOperation(async () => {
-			const conn = await getConnection();
-			const db = await initializeDuckDB();
-			for (const [, internalTableName] of this.tableMap.entries()) {
-				try {
-					await conn.query(`DROP TABLE IF EXISTS ${internalTableName}`);
-				} catch {}
-				try {
-					await db.dropFile(`${internalTableName}.parquet`);
-				} catch {}
-			}
-			this.tableMap.clear();
+async function fetchAndValidate(options) {
+	const log = getOxyAppLogger();
+	const injected = readInjectedAppConfig();
+	const manifestUrl = options.manifestUrl ?? defaultManifestUrl(injected);
+	log.log("info", "loading manifest", {
+		manifestUrl,
+		injectionPresent: !!injected,
+		orgSlug: injected?.orgSlug,
+		appSlug: injected?.slug,
+		appId: injected?.appId
+	});
+	const startedAt = Date.now();
+	const res = await fetch(manifestUrl, { credentials: "same-origin" });
+	if (!res.ok) {
+		log.log("error", "manifest fetch failed", {
+			manifestUrl,
+			status: res.status,
+			statusText: res.statusText
 		});
+		throw new Error(`Failed to load oxy-app.json from ${manifestUrl} (HTTP ${res.status}). The customer-app repo must commit this file alongside the bundle.`);
 	}
-};
+	const manifest = validateManifest(await res.json(), manifestUrl);
+	const resolved = {
+		manifest,
+		productNames: [],
+		orgSlug: injected?.orgSlug ?? "",
+		appSlug: injected?.slug ?? "",
+		apiBaseUrl: injected?.apiBaseUrl || "",
+		appId: injected?.appId,
+		projectId: injected?.projectId ?? manifest.projectId
+	};
+	log.log("info", "manifest ready", {
+		durationMs: Date.now() - startedAt,
+		schemaVersion: manifest.schemaVersion,
+		slug: manifest.slug
+	});
+	return resolved;
+}
 /**
-* Helper function to quickly read a Parquet blob and execute a query
-*
-* @param blob - Parquet file as Blob
-* @param tableName - Name to use for the table in queries (default: 'data')
-* @param sql - SQL query to execute (optional, defaults to SELECT * FROM tableName)
-* @returns Query result
+* Default manifest URL.
 *
-* @example
-* ```typescript
-* const blob = await client.getFile('data/sales.parquet');
-* const result = await queryParquet(blob, 'sales', 'SELECT product, SUM(amount) as total FROM sales GROUP BY product');
-* console.log(result);
-* ```
+* Resolution order (bundler-agnostic):
+*   1. `window.__OXY_APP__.orgSlug`/`slug` injection → the canonical
+*      `/customer-apps/<org>/<app>/oxy-app.json`. Works for every
+*      bundle oxy serves regardless of how it was built.
+*   2. `NEXT_PUBLIC_APP_BASE_PATH` env var — kept for backward compat
+*      with Next.js bundles that bake basePath at build time.
+*   3. Empty basePath → `/oxy-app.json` (only matches when running in
+*      a `vite dev` / `next dev` root mount; will 404 under oxy).
 */
-async function queryParquet(blob, tableName = "data", sql) {
-	const reader = new ParquetReader();
-	await reader.registerParquet(blob, tableName);
-	const query = sql || `SELECT * FROM ${tableName}`;
-	const result = await reader.query(query);
-	await reader.close();
-	return result;
+function defaultManifestUrl(injected) {
+	if (injected?.orgSlug && injected?.slug) return `/customer-apps/${encodeURIComponent(injected.orgSlug)}/${encodeURIComponent(injected.slug)}/oxy-app.json`;
+	return "/oxy-app.json";
 }
 /**
-* Helper function to read Parquet file and get all data
+* Validate a v2 manifest. Required: schemaVersion === 2, slug (non-empty).
+* Optional: name (display), orgSlug (dev-time hint for the admin dialog),
+* projectId (dev-time hint when there's no server-side injection).
 *
-* @param blob - Parquet file as Blob
-* @param tableName - Name to use for the table (default: 'data')
-* @param limit - Maximum number of rows (optional)
-* @returns Query result
-*
-* @example
-* ```typescript
-* const blob = await client.getFile('data/sales.parquet');
-* const data = await readParquet(blob, 'sales', 1000);
-* console.log(`Loaded ${data.rowCount} rows`);
-* ```
+* At serve time, oxy's identity injection (window.__OXY_APP__) overrides
+* the manifest's orgSlug/projectId — the manifest fields are advisory.
 */
-async function readParquet(blob, tableName = "data", limit) {
-	const reader = new ParquetReader();
-	await reader.registerParquet(blob, tableName);
-	const result = await reader.getAll(tableName, limit);
-	await reader.close();
-	return result;
+function validateManifest(raw, url) {
+	if (!isRecord(raw)) throw new Error(`Manifest at ${url} is not a JSON object`);
+	if (raw.schemaVersion !== 2) throw new Error(`oxy-app.json: schemaVersion must be 2 (got ${JSON.stringify(raw.schemaVersion)}). v1 manifests are no longer supported — upgrade to the identity-only shape.`);
+	if (raw.products !== void 0 || raw.writers !== void 0) throw new Error(`oxy-app.json is schemaVersion 2 (identity-only); \`products\` and \`writers\` are no longer supported`);
+	if (typeof raw.slug !== "string" || !raw.slug.trim()) throw new Error("oxy-app.json: `slug` is required and must be a non-empty string");
+	return {
+		schemaVersion: 2,
+		name: typeof raw.name === "string" ? raw.name : void 0,
+		slug: raw.slug,
+		orgSlug: typeof raw.orgSlug === "string" ? raw.orgSlug : void 0,
+		projectId: typeof raw.projectId === "string" ? raw.projectId : void 0
+	};
+}
+function isRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
 //#endregion
-//#region src/client.ts
+//#region src/customer-app/interpolate.ts
 /**
-* Oxy API Client for interacting with Oxy data
+* Interpolate `{{ params.X }}` and `{{ params.X | sqlquote }}` placeholders
+* in a SQL template.
+*
+* - `{{ params.X | sqlquote }}` — quote strings ('foo'), pass numbers and
+*   booleans raw, nullish becomes NULL. Mirrors the server's Jinja sqlquote
+*   filter.
+* - `{{ params.X }}` — raw pass-through. Used for already-trusted values
+*   (numbers, identifiers the caller has validated). Caller is responsible
+*   for safety.
+*
+* Not a security boundary. The server still gates SQL execution by
+* project membership. Bundles that accept untrusted user input should
+* use `| sqlquote` or validate/coerce before passing.
 */
-var OxyClient = class OxyClient {
-	constructor(config) {
-		this.config = config;
-	}
-	/**
-	* Creates an OxyClient instance asynchronously with support for postMessage authentication
-	*
-	* This is the recommended method when using the SDK in an iframe that needs to
-	* obtain authentication from the parent window via postMessage.
-	*
-	* @param config - Optional configuration overrides
-	* @returns Promise resolving to OxyClient instance
-	* @throws Error if required configuration is missing
-	* @throws PostMessageAuthTimeoutError if parent doesn't respond
-	*
-	* @example
-	* ```typescript
-	* // In an iframe - automatic postMessage auth
-	* const client = await OxyClient.create({
-	*   parentOrigin: 'https://app.example.com',
-	*   projectId: 'my-project-id',
-	*   baseUrl: 'https://api.oxy.tech'
-	* });
-	*
-	* // Use the client normally
-	* const apps = await client.listApps();
-	* ```
-	*/
-	static async create(config) {
-		return new OxyClient(await createConfigAsync(config));
-	}
-	/**
-	* Encodes a file path to base64 for use in API URLs.
-	* Handles Unicode characters (e.g., emojis) properly in both Node.js and browser.
-	*/
-	encodePathBase64(path) {
-		if (typeof Buffer !== "undefined") return Buffer.from(path).toString("base64");
-		else return btoa(encodeURIComponent(path).replace(/%([0-9A-F]{2})/g, (_, p1) => String.fromCharCode(parseInt(p1, 16))));
-	}
-	/**
-	* Makes an authenticated HTTP request to the Oxy API
-	*/
-	async request(endpoint, options = {}) {
-		const url = `${this.config.baseUrl}${endpoint}`;
-		const headers = {
-			"Content-Type": "application/json",
-			...options.headers || {}
-		};
-		if (this.config.apiKey) headers.Authorization = `Bearer ${this.config.apiKey}`;
-		const controller = new AbortController();
-		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout || 3e4);
-		try {
-			const response = await fetch(url, {
-				...options,
-				headers,
-				signal: controller.signal
-			});
-			clearTimeout(timeoutId);
-			if (!response.ok) {
-				const errorText = await response.text().catch(() => "Unknown error");
-				throw {
-					message: `API request failed: ${response.statusText}`,
-					status: response.status,
-					details: errorText
-				};
-			}
-			if ((typeof options.headers === "object" && options.headers !== null ? options.headers.Accept : void 0) === "application/octet-stream") return response.blob();
-			return response.json();
-		} catch (error) {
-			clearTimeout(timeoutId);
-			if (error instanceof Error && error.name === "AbortError") throw new Error(`Request timeout after ${this.config.timeout || 3e4}ms`);
-			throw error;
+function interpolateSqlParams(sql, params) {
+	return sql.replace(/\{\{\s*params\.([a-zA-Z0-9_]+)(\s*\|\s*sqlquote)?\s*\}\}/g, (_match, key, sqlquote) => {
+		const v = params[key];
+		if (v === null || v === void 0) return "NULL";
+		if (sqlquote) {
+			if (typeof v === "number" || typeof v === "boolean") return String(v);
+			return `'${String(v).replace(/'/g, "''")}'`;
 		}
-	}
-	/**
-	* Builds query parameters including optional branch
-	*/
-	buildQueryParams(additionalParams = {}) {
-		const params = { ...additionalParams };
-		if (this.config.branch) params.branch = this.config.branch;
-		const queryString = new URLSearchParams(params).toString();
-		return queryString ? `?${queryString}` : "";
-	}
-	/**
-	* Lists all apps in the project
-	*
-	* @returns Array of app items
-	*
-	* @example
-	* ```typescript
-	* const apps = await client.listApps();
-	* console.log('Available apps:', apps);
-	* ```
-	*/
-	async listApps() {
-		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/apps${query}`);
-	}
-	/**
-	* Gets data for a specific app
-	*
-	* @param appPath - Relative path to the app file (e.g., 'my-app.app.yml')
-	* @returns App data response
-	*
-	* @example
-	* ```typescript
-	* const data = await client.getAppData('dashboard.app.yml');
-	* if (data.error) {
-	*   console.error('Error:', data.error);
-	* } else {
-	*   console.log('App data:', data.data);
-	* }
-	* ```
-	*/
-	async getAppData(appPath) {
-		const pathb64 = this.encodePathBase64(appPath);
-		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/apps/${pathb64}${query}`);
-	}
-	/**
-	* Runs an app and returns fresh data (bypasses cache)
-	*
-	* @param appPath - Relative path to the app file
-	* @returns App data response
-	*
-	* @example
-	* ```typescript
-	* const data = await client.runApp('dashboard.app.yml');
-	* console.log('Fresh app data:', data.data);
-	* ```
-	*/
-	async runApp(appPath) {
-		const pathb64 = this.encodePathBase64(appPath);
-		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/apps/${pathb64}/run${query}`, { method: "POST" });
-	}
-	/**
-	* Gets display configurations for an app
-	*
-	* @param appPath - Relative path to the app file
-	* @returns Display configurations with potential errors
-	*
-	* @example
-	* ```typescript
-	* const displays = await client.getDisplays('dashboard.app.yml');
-	* displays.displays.forEach(d => {
-	*   if (d.error) {
-	*     console.error('Display error:', d.error);
-	*   } else {
-	*     console.log('Display:', d.display);
-	*   }
-	* });
-	* ```
-	*/
-	async getDisplays(appPath) {
-		const pathb64 = this.encodePathBase64(appPath);
-		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/apps/${pathb64}/displays${query}`);
-	}
-	/**
-	* Gets a file from the app state directory (e.g., generated charts, images)
-	*
-	* This is useful for retrieving generated assets like charts, images, or other
-	* files produced by app workflows and stored in the state directory.
-	*
-	* @param filePath - Relative path to the file in state directory
-	* @returns Blob containing the file data
-	*
-	* @example
-	* ```typescript
-	* // Get a generated chart image
-	* const blob = await client.getFile('charts/sales-chart.png');
-	* const imageUrl = URL.createObjectURL(blob);
-	*
-	* // Use in an img tag
-	* document.querySelector('img').src = imageUrl;
-	* ```
-	*
-	* @example
-	* ```typescript
-	* // Download a file
-	* const blob = await client.getFile('exports/data.csv');
-	* const a = document.createElement('a');
-	* a.href = URL.createObjectURL(blob);
-	* a.download = 'data.csv';
-	* a.click();
-	* ```
-	*/
-	async getFile(filePath) {
-		const pathb64 = this.encodePathBase64(filePath);
-		const query = this.buildQueryParams();
-		return this.request(`/${this.config.projectId}/apps/file/${pathb64}${query}`, { headers: { Accept: "application/octet-stream" } });
-	}
-	/**
-	* Gets a file URL for direct browser access
-	*
-	* This returns a URL that can be used directly in img tags, fetch calls, etc.
-	* The URL includes authentication via query parameters.
-	*
-	* @param filePath - Relative path to the file in state directory
-	* @returns Full URL to the file
-	*
-	* @example
-	* ```typescript
-	* const imageUrl = client.getFileUrl('charts/sales-chart.png');
-	*
-	* // Use directly in img tag (in environments where query-based auth is supported)
-	* document.querySelector('img').src = imageUrl;
-	* ```
-	*/
-	getFileUrl(filePath) {
-		const pathb64 = this.encodePathBase64(filePath);
-		const query = this.buildQueryParams();
-		return `${this.config.baseUrl}/${this.config.projectId}/apps/file/${pathb64}${query}`;
-	}
-	/**
-	* Fetches a parquet file and parses it into table data
-	*
-	* @param filePath - Relative path to the parquet file
-	* @param limit - Maximum number of rows to return (default: 100)
-	* @returns TableData with columns and rows
-	*
-	* @example
-	* ```typescript
-	* const tableData = await client.getTableData('data/sales.parquet', 50);
-	* console.log(tableData.columns);
-	* console.log(tableData.rows);
-	* console.log(`Total rows: ${tableData.total_rows}`);
-	* ```
-	*/
-	async getTableData(filePath, limit = 100) {
-		const result = await readParquet(await this.getFile(filePath), "data", limit);
-		return {
-			columns: result.columns,
-			rows: result.rows,
-			total_rows: result.rowCount
-		};
-	}
-};
+		return String(v);
+	});
+}
 
 //#endregion
-//#region src/sdk.ts
+//#region src/customer-app/markdown.ts
 /**
-* OxySDK provides a unified interface for fetching data from Oxy and querying it with SQL.
-* It combines OxyClient (for API calls) and ParquetReader (for SQL queries) into a single,
-* easy-to-use interface.
-*
-* @example
-* ```typescript
-* // Create SDK instance
-* const sdk = new OxySDK({ apiKey: 'your-key', projectId: 'your-project' });
+* Allowlist for `[text](url)` href values in agent-emitted markdown.
+* Markdown comes from an LLM, which sits across an external trust
+* boundary — without this filter, a `javascript:` URL produced by
+* the model would render as a clickable XSS in the bundle's origin.
 *
-* // Load a parquet file and query it
-* await sdk.loadFile('data/sales.parquet', 'sales');
-* const result = await sdk.query('SELECT * FROM sales WHERE amount > 1000');
-* console.log(result.rows);
+* Accepts:
+*   - http(s):// absolute URLs
+*   - mailto: addresses
+*   - root-relative paths (`/foo`)
+*   - same-page fragments (`#section`)
 *
-* // Clean up when done
-* await sdk.close();
-* ```
+* Rejects everything else, including `javascript:`, `data:`,
+* protocol-relative `//evil.com`, and any other scheme. Comparison
+* is case-insensitive after stripping leading whitespace + ASCII
+* control bytes (browsers strip these before scheme resolution, so
+* `java\tscript:` would otherwise slip past a naive prefix check).
 */
-var OxySDK = class OxySDK {
-	constructor(config) {
-		this.client = new OxyClient(config);
-		this.reader = new ParquetReader();
-	}
-	/**
-	* Creates an OxySDK instance asynchronously with support for postMessage authentication
-	*
-	* @param config - Optional configuration overrides
-	* @returns Promise resolving to OxySDK instance
-	*
-	* @example
-	* ```typescript
-	* // In an iframe - automatic postMessage auth
-	* const sdk = await OxySDK.create({
-	*   parentOrigin: 'https://app.example.com',
-	*   projectId: 'my-project-id'
-	* });
-	* ```
-	*/
-	static async create(config) {
-		return new OxySDK(await createConfigAsync(config));
+function isSafeLinkHref(raw) {
+	let cleaned = "";
+	for (let i = 0; i < raw.length; i++) {
+		const cc = raw.charCodeAt(i);
+		if (cc > 32 && cc !== 127) cleaned += raw[i];
 	}
-	/**
-	* Load a Parquet file from Oxy and register it for SQL queries
-	*
-	* @param filePath - Path to the parquet file in the app state directory
-	* @param tableName - Name to use for the table in SQL queries
-	*
-	* @example
-	* ```typescript
-	* await sdk.loadFile('data/sales.parquet', 'sales');
-	* await sdk.loadFile('data/customers.parquet', 'customers');
-	*
-	* const result = await sdk.query(`
-	*   SELECT s.*, c.name
-	*   FROM sales s
-	*   JOIN customers c ON s.customer_id = c.id
-	* `);
-	* ```
-	*/
-	async loadFile(filePath, tableName) {
-		const blob = await this.client.getFile(filePath);
-		await this.reader.registerParquet(blob, tableName);
+	if (cleaned === "") return false;
+	if (cleaned.startsWith("#") || cleaned.startsWith("/")) {
+		if (cleaned.startsWith("//")) return false;
+		return true;
 	}
-	/**
-	* Load multiple Parquet files at once
-	*
-	* @param files - Array of file paths and table names
-	*
-	* @example
-	* ```typescript
-	* await sdk.loadFiles([
-	*   { filePath: 'data/sales.parquet', tableName: 'sales' },
-	*   { filePath: 'data/customers.parquet', tableName: 'customers' },
-	*   { filePath: 'data/products.parquet', tableName: 'products' }
-	* ]);
-	*
-	* const result = await sdk.query('SELECT * FROM sales');
-	* ```
-	*/
-	async loadFiles(files) {
-		for (const file of files) await this.loadFile(file.filePath, file.tableName);
-	}
-	/**
-	* Load all data from an app's data container
-	*
-	* This fetches the app's data and registers all parquet files using their container keys as table names.
-	*
-	* @param appPath - Path to the app file
-	* @returns DataContainer with file references
-	*
-	* @example
-	* ```typescript
-	* // If app has data: { sales: { file_path: 'data/sales.parquet' } }
-	* const data = await sdk.loadAppData('dashboard.app.yml');
-	* // Now you can query the 'sales' table
-	* const result = await sdk.query('SELECT * FROM sales LIMIT 10');
-	* ```
-	*/
-	async loadAppData(appPath) {
-		const appDataResponse = await this.client.getAppData(appPath);
-		if (appDataResponse.error) throw new Error(`Failed to load app data: ${appDataResponse.error}`);
-		if (!appDataResponse.data) return null;
-		const loadPromises = Object.entries(appDataResponse.data).map(async ([tableName, fileRef]) => {
-			await this.loadFile(fileRef.file_path, tableName);
+	const lower = cleaned.toLowerCase();
+	return lower.startsWith("http://") || lower.startsWith("https://") || lower.startsWith("mailto:");
+}
+
+//#endregion
+//#region src/customer-app/react.tsx
+function defaultFetcher(input, init) {
+	return fetch(input, {
+		credentials: "include",
+		...init
+	});
+}
+const OxyAppContext = React.createContext(void 0);
+/**
+* Top-level provider. Loads the manifest once on mount; children only
+* render after the manifest is ready (or the error fallback fires).
+*/
+function OxyAppProvider(props) {
+	const { manifestOptions, fallback, errorFallback, fetcher: fetcherProp, children } = props;
+	const fetcher = fetcherProp ?? defaultFetcher;
+	const [state, setState] = React.useState({
+		status: "loading",
+		fetcher
+	});
+	React.useEffect(() => {
+		let cancelled = false;
+		loadCustomerAppManifest(manifestOptions).then((resolved) => {
+			if (!cancelled) setState({
+				status: "ready",
+				resolved,
+				fetcher
+			});
+		}).catch((e) => {
+			if (!cancelled) setState({
+				status: "error",
+				error: interpretCustomerAppError(e),
+				fetcher
+			});
 		});
-		await Promise.all(loadPromises);
-		return appDataResponse.data;
-	}
-	/**
-	* Execute a SQL query against loaded data
-	*
-	* @param sql - SQL query to execute
-	* @returns Query result with columns and rows
-	*
-	* @example
-	* ```typescript
-	* await sdk.loadFile('data/sales.parquet', 'sales');
-	*
-	* const result = await sdk.query('SELECT product, SUM(amount) as total FROM sales GROUP BY product');
-	* console.log(result.columns); // ['product', 'total']
-	* console.log(result.rows);    // [['Product A', 1000], ['Product B', 2000]]
-	* console.log(result.rowCount); // 2
-	* ```
-	*/
-	async query(sql) {
-		return this.reader.query(sql);
-	}
-	/**
-	* Get all data from a loaded table
-	*
-	* @param tableName - Name of the table
-	* @param limit - Maximum number of rows (optional)
-	* @returns Query result
-	*
-	* @example
-	* ```typescript
-	* await sdk.loadFile('data/sales.parquet', 'sales');
-	* const allData = await sdk.getAll('sales');
-	* const first100 = await sdk.getAll('sales', 100);
-	* ```
-	*/
-	async getAll(tableName, limit) {
-		return this.reader.getAll(tableName, limit);
-	}
-	/**
-	* Get schema information for a loaded table
-	*
-	* @param tableName - Name of the table
-	* @returns Schema information
-	*
-	* @example
-	* ```typescript
-	* await sdk.loadFile('data/sales.parquet', 'sales');
-	* const schema = await sdk.getSchema('sales');
-	* console.log(schema.columns); // ['column_name', 'column_type', ...]
-	* console.log(schema.rows);    // [['id', 'INTEGER'], ['name', 'VARCHAR'], ...]
-	* ```
-	*/
-	async getSchema(tableName) {
-		return this.reader.getSchema(tableName);
-	}
-	/**
-	* Get row count for a loaded table
-	*
-	* @param tableName - Name of the table
-	* @returns Number of rows
-	*
-	* @example
-	* ```typescript
-	* await sdk.loadFile('data/sales.parquet', 'sales');
-	* const count = await sdk.count('sales');
-	* console.log(`Total rows: ${count}`);
-	* ```
-	*/
-	async count(tableName) {
-		return this.reader.count(tableName);
-	}
-	/**
-	* Get direct access to the underlying OxyClient
-	*
-	* Useful for advanced operations like listing apps, getting displays, etc.
-	*
-	* @returns The OxyClient instance
-	*
-	* @example
-	* ```typescript
-	* const apps = await sdk.getClient().listApps();
-	* const displays = await sdk.getClient().getDisplays('my-app.app.yml');
-	* ```
-	*/
-	getClient() {
-		return this.client;
-	}
-	/**
-	* Get direct access to the underlying ParquetReader
-	*
-	* Useful for advanced operations like registering blobs directly.
-	*
-	* @returns The ParquetReader instance
-	*
-	* @example
-	* ```typescript
-	* const myBlob = new Blob([parquetData]);
-	* await sdk.getReader().registerParquet(myBlob, 'mydata');
-	* ```
-	*/
-	getReader() {
-		return this.reader;
+		return () => {
+			cancelled = true;
+		};
+	}, [manifestOptions, fetcher]);
+	if (state.status === "error" && state.error) {
+		const err = state.error;
+		return /* @__PURE__ */ React.createElement(OxyAppContext.Provider, { value: state }, errorFallback ? errorFallback(err) : defaultErrorFallback(err));
 	}
-	/**
-	* Close and cleanup all resources
-	*
-	* This clears all loaded data and releases resources. Call this when you're done with the SDK.
-	*
-	* @example
-	* ```typescript
-	* const sdk = new OxySDK({ apiKey: 'key', projectId: 'project' });
-	* await sdk.loadFile('data/sales.parquet', 'sales');
-	* const result = await sdk.query('SELECT * FROM sales');
-	* await sdk.close(); // Clean up
-	* ```
-	*/
-	async close() {
-		await this.reader.close();
+	if (state.status === "loading") return /* @__PURE__ */ React.createElement(OxyAppContext.Provider, { value: state }, fallback ?? null);
+	return /* @__PURE__ */ React.createElement(OxyAppContext.Provider, { value: state }, children);
+}
+function defaultErrorFallback(err) {
+	return /* @__PURE__ */ React.createElement("div", { style: {
+		margin: "2rem auto",
+		maxWidth: "640px",
+		padding: "1rem",
+		border: "1px solid #fca5a5",
+		background: "#fee2e2",
+		color: "#991b1b",
+		borderRadius: "8px",
+		fontFamily: "system-ui, -apple-system, sans-serif",
+		fontSize: "14px"
+	} }, /* @__PURE__ */ React.createElement("div", { style: { fontWeight: 600 } }, err.title), /* @__PURE__ */ React.createElement("pre", { style: {
+		fontSize: "12px",
+		marginTop: "4px"
+	} }, err.message), /* @__PURE__ */ React.createElement("div", { style: { marginTop: "12px" } }, /* @__PURE__ */ React.createElement("strong", null, "What to try:"), " ", err.hint));
+}
+/**
+* Emit a one-time `console.warn` the first time a beta hook is
+* used in a given page load. Bundles upgrading from a future GA
+* release won't see the warning; the message lets us flag rough
+* edges without breaking the build.
+*/
+const _warnedBeta = /* @__PURE__ */ new Set();
+function warnBetaOnce(name) {
+	if (_warnedBeta.has(name)) return;
+	_warnedBeta.add(name);
+	if (typeof console !== "undefined" && typeof console.warn === "function") console.warn(`[@oxy-hq/sdk] \`${name}\` is in beta — interface and behavior may change. See https://github.com/oxy-hq/customer-apps for caveats and the migration guide.`);
+}
+/**
+* Error thrown by all customer-app hooks when an API call returns a
+* non-2xx response. Carries the structured `code` + `hint` the server
+* emits so bundle UIs can render an actionable message instead of
+* "404: { ...json... }".
+*
+* The server contract is documented in
+* `crates/app/src/server/api/projects/agent_ask.rs` and
+* `procedure_run.rs` — both emit `{ message, code?, hint? }` as JSON.
+* Hooks that previously wrapped the raw text in `new Error()` now
+* throw this type instead.
+*/
+var OxyApiError = class extends Error {
+	constructor(opts) {
+		const base = opts.message || `HTTP ${opts.status}`;
+		const code = opts.code ? ` [${opts.code}]` : "";
+		const hint = opts.hint ? `\n\n${opts.hint}` : "";
+		super(`${base}${code}${hint}`);
+		this.name = "OxyApiError";
+		this.status = opts.status;
+		this.code = opts.code ?? null;
+		this.hint = opts.hint ?? null;
 	}
 };
-
-//#endregion
-//#region src/react.tsx
 /**
-* React context for OxySDK
+* Read a non-2xx response from oxy and return an `OxyApiError`.
+* Parses the JSON envelope when present; falls back to raw text
+* (truncated to 240 chars so a runaway HTML error page doesn't
+* dominate the bundle UI).
 */
-const OxyContext = createContext(void 0);
+async function apiErrorFromResponse(resp) {
+	let body;
+	let raw = "";
+	try {
+		raw = await resp.text();
+		body = raw ? JSON.parse(raw) : void 0;
+	} catch {}
+	if (body && typeof body === "object") {
+		const b = body;
+		return new OxyApiError({
+			status: resp.status,
+			message: typeof b.message === "string" ? b.message : `HTTP ${resp.status}`,
+			code: typeof b.code === "string" ? b.code : null,
+			hint: typeof b.hint === "string" ? b.hint : null
+		});
+	}
+	const snippet = raw.length > 240 ? `${raw.slice(0, 237)}…` : raw;
+	return new OxyApiError({
+		status: resp.status,
+		message: snippet || `HTTP ${resp.status}`
+	});
+}
 /**
-* Provider component that initializes and provides OxySDK to child components
-*
-* @example
-* ```tsx
-* // Synchronous initialization with config
-* function App() {
-*   return (
-*     <OxyProvider config={{
-*       apiKey: 'your-key',
-*       projectId: 'your-project',
-*       baseUrl: 'https://api.oxy.tech'
-*     }}>
-*       <Dashboard />
-*     </OxyProvider>
-*   );
-* }
-* ```
+* Read the resolved manifest from context. Throws if called outside
+* `<OxyAppProvider>` — that's a programmer error worth surfacing
+* loudly, not silently swallowing.
+*/
+function useResolvedManifest() {
+	const ctx = React.useContext(OxyAppContext);
+	if (!ctx) throw new Error("useResolvedManifest must be called inside <OxyAppProvider>");
+	if (ctx.status !== "ready" || !ctx.resolved) throw new Error("useResolvedManifest called before manifest finished loading. Use the provider's `fallback` prop to render while loading.");
+	return ctx.resolved;
+}
+/**
+* Low-level hook that returns the raw context value (including the
+* fetcher). Prefer `useResolvedManifest` for manifest access; use
+* this only when you need the fetcher or projectId without requiring
+* the manifest to be ready (e.g. inside `useQuery`).
+*/
+function useOxyApp() {
+	const ctx = React.useContext(OxyAppContext);
+	if (!ctx) throw new Error("useOxyApp must be called inside <OxyAppProvider>");
+	return {
+		projectId: ctx.resolved?.projectId,
+		fetcher: ctx.fetcher
+	};
+}
+/**
+* Execute an ad-hoc SQL query against the project linked to this
+* customer app. The query is specified inline by the caller; no
+* manifest declaration is involved.
 *
-* @example
-* ```tsx
-* // Async initialization (for iframe/postMessage auth)
-* function App() {
-*   return (
-*     <OxyProvider
-*       useAsync
-*       config={{ parentOrigin: 'https://app.example.com' }}
-*     >
-*       <Dashboard />
-*     </OxyProvider>
-*   );
-* }
-* ```
+* Re-runs whenever `input` or enabled `params` change. Use the
+* `enabled` option to defer the first fetch until required data is
+* available (e.g. a user-supplied filter value).
+*/
+function useQuery(input, opts = {}) {
+	const { projectId, fetcher } = useOxyApp();
+	const enabled = opts.enabled !== false;
+	const paramsKey = JSON.stringify(opts.params);
+	const sqlWithParams = React.useMemo(() => interpolateSqlParams(input.sql, opts.params ?? {}), [input.sql, paramsKey]);
+	const [state, setState] = React.useState({
+		rows: [],
+		columns: [],
+		loading: enabled && !!projectId,
+		error: null
+	});
+	const [nonce, setNonce] = React.useState(0);
+	React.useEffect(() => {
+		if (!enabled || !projectId) {
+			setState((s) => s.loading ? {
+				...s,
+				loading: false
+			} : s);
+			return;
+		}
+		const ctrl = new AbortController();
+		let cancelled = false;
+		setState((s) => ({
+			...s,
+			loading: true,
+			error: null
+		}));
+		const body = JSON.stringify({
+			sql: sqlWithParams,
+			...input.database ? { database: input.database } : {}
+		});
+		fetcher(`/api/projects/${projectId}/query`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body,
+			signal: ctrl.signal
+		}).then(async (resp) => {
+			if (!resp.ok) throw await apiErrorFromResponse(resp);
+			return resp.json();
+		}).then(({ columns, rows }) => {
+			if (cancelled) return;
+			setState({
+				rows: rows.map((r) => Object.fromEntries(columns.map((c, i) => [c, r[i]]))),
+				columns,
+				loading: false,
+				error: null
+			});
+		}).catch((err) => {
+			if (cancelled) return;
+			if (err instanceof DOMException && err.name === "AbortError") return;
+			setState((s) => ({
+				...s,
+				loading: false,
+				error: err instanceof Error ? err : new Error(String(err))
+			}));
+		});
+		return () => {
+			cancelled = true;
+			ctrl.abort();
+		};
+	}, [
+		enabled,
+		projectId,
+		sqlWithParams,
+		input.database,
+		nonce,
+		fetcher
+	]);
+	return {
+		rows: state.rows,
+		columns: state.columns,
+		loading: state.loading,
+		error: state.error,
+		refetch: () => setNonce((n) => n + 1)
+	};
+}
+/**
+* Run a semantic-layer query against the project's `.view.yml` /
+* `.topic.yml` definitions. The server compiles to SQL and executes
+* through the same connector path as `useQuery`, so result shape
+* matches.
 *
-* @example
-* ```tsx
-* // With environment variables
-* import { createConfig } from '@oxy/sdk';
+* Re-runs whenever the input shape changes (deep-compared via JSON).
+* Use `opts.enabled = false` to defer the first fetch until required
+* inputs (e.g. a user-picked filter value) are available.
+*/
+function useSemanticQuery(input, opts = {}) {
+	const { projectId, fetcher } = useOxyApp();
+	const enabled = opts.enabled !== false;
+	const debug = opts.debug === true;
+	const inputKey = React.useMemo(() => JSON.stringify(input), [input]);
+	const [state, setState] = React.useState({
+		rows: [],
+		columns: [],
+		truncated: false,
+		sql: null,
+		loading: enabled && !!projectId,
+		error: null
+	});
+	const [nonce, setNonce] = React.useState(0);
+	React.useEffect(() => {
+		if (!enabled || !projectId) {
+			setState((s) => s.loading ? {
+				...s,
+				loading: false
+			} : s);
+			return;
+		}
+		const ctrl = new AbortController();
+		let cancelled = false;
+		setState((s) => ({
+			...s,
+			loading: true,
+			error: null
+		}));
+		const body = JSON.stringify({
+			v: 1,
+			topic: input.topic,
+			dimensions: input.dimensions ?? [],
+			measures: input.measures ?? [],
+			time_dimensions: input.time_dimensions ?? [],
+			filters: input.filters ?? [],
+			...input.limit != null ? { limit: input.limit } : {}
+		});
+		fetcher(`/api/projects/${projectId}/semantic-query${debug ? "?debug=1" : ""}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body,
+			signal: ctrl.signal
+		}).then(async (resp) => {
+			if (!resp.ok) throw await apiErrorFromResponse(resp);
+			return resp.json();
+		}).then(({ columns, rows, truncated, sql }) => {
+			if (cancelled) return;
+			setState({
+				rows: rows.map((r) => Object.fromEntries(columns.map((c, i) => [c, r[i]]))),
+				columns,
+				truncated,
+				sql: sql ?? null,
+				loading: false,
+				error: null
+			});
+		}).catch((err) => {
+			if (cancelled) return;
+			if (err instanceof DOMException && err.name === "AbortError") return;
+			setState((s) => ({
+				...s,
+				loading: false,
+				error: err instanceof Error ? err : new Error(String(err))
+			}));
+		});
+		return () => {
+			cancelled = true;
+			ctrl.abort();
+		};
+	}, [
+		enabled,
+		projectId,
+		inputKey,
+		debug,
+		nonce,
+		fetcher
+	]);
+	return {
+		rows: state.rows,
+		columns: state.columns,
+		truncated: state.truncated,
+		sql: state.sql,
+		loading: state.loading,
+		error: state.error,
+		refetch: () => setNonce((n) => n + 1)
+	};
+}
+const PROCEDURE_POLL_MS = 2e3;
+const PROCEDURE_BACKOFF_MS = 5e3;
+const PROCEDURE_MAX_WAIT_MS = 3600 * 1e3;
+/**
+* @beta Long-running procedure runner. The wire shape works end-to-end
+* (start → poll → cancel; runs survive server restarts via the
+* `customer_app_procedure_runs` table) but a few rough edges remain
+* before this is GA-ready:
 *
-* function App() {
-*   return (
-*     <OxyProvider config={createConfig()}>
-*       <Dashboard />
-*     </OxyProvider>
-*   );
-* }
-* ```
+*   - Hint surfaces for `procedure_not_found` are correct but the
+*     procedure-discovery rules (which directories the server scans,
+*     case-sensitivity, branch awareness) aren't documented yet.
+*   - Cancellation across multi-instance deployments leans on a
+*     periodic sweep — fine for now, but expect occasional latency
+*     between `cancel()` and the run actually stopping.
+*   - Progress reporting requires the procedure to emit named
+*     steps; bundles get `progress: null` until that lands.
 *
-* @example
-* ```tsx
-* // With loading and error slots
-* function App() {
-*   return (
-*     <OxyProvider
-*       config={createConfig()}
-*       loadingFallback={<div>Loading SDK...</div>}
-*       errorFallback={(error) => <div>Error: {error.message}</div>}
-*     >
-*       <Dashboard />
-*     </OxyProvider>
-*   );
-* }
-* ```
+* The API surface is stable; expect breaking changes only if the
+* server-side `customer_app_procedure_runs` schema changes.
 */
-function OxyProvider({ children, config, useAsync = false, appPath, files, onReady, onError, loadingFallback, errorFallback }) {
-	const [sdk, setSdk] = useState(null);
-	const [isLoading, setIsLoading] = useState(true);
-	const [error, setError] = useState(null);
-	useEffect(() => {
-		let mounted = true;
-		let sdkInstance = null;
-		async function initializeSDK() {
+function useProcedureRun(input, opts = {}) {
+	warnBetaOnce("useProcedureRun");
+	const { projectId, fetcher } = useOxyApp();
+	const pollMs = opts.pollIntervalMs ?? PROCEDURE_POLL_MS;
+	const backoffMs = opts.pollIntervalBackoffMs ?? PROCEDURE_BACKOFF_MS;
+	const maxWaitMs = opts.maxWaitMs ?? PROCEDURE_MAX_WAIT_MS;
+	const [state, setState] = React.useState({
+		state: "idle",
+		progress: null,
+		result: null,
+		error: null
+	});
+	const inflight = React.useRef({});
+	const cancel = React.useCallback(() => {
+		const runId = inflight.current.runId;
+		if (!projectId || !runId) return;
+		inflight.current.abort?.abort();
+		inflight.current.runId = void 0;
+		fetcher(`/api/projects/${projectId}/procedures/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" }).catch(() => {});
+		setState({
+			state: "failed",
+			progress: null,
+			result: null,
+			error: /* @__PURE__ */ new Error("procedure cancelled by user")
+		});
+	}, [projectId, fetcher]);
+	const run = React.useCallback((params) => {
+		if (!projectId) {
+			setState((s) => ({
+				...s,
+				state: "failed",
+				error: /* @__PURE__ */ new Error("project not configured")
+			}));
+			return;
+		}
+		inflight.current.abort?.abort();
+		const ctrl = new AbortController();
+		inflight.current = { abort: ctrl };
+		setState({
+			state: "running",
+			progress: null,
+			result: null,
+			error: null
+		});
+		(async () => {
 			try {
-				setIsLoading(true);
-				setError(null);
-				if (useAsync) {
-					sdkInstance = await OxySDK.create(config);
-					if (appPath) await sdkInstance.loadAppData(appPath);
-					if (files) {
-						const fileEntries = Object.entries(files).map(([tableName, filePath]) => ({
-							tableName,
-							filePath
+				const body = JSON.stringify({
+					v: 1,
+					...params ? { params } : {}
+				});
+				const startResp = await fetcher(`/api/projects/${projectId}/procedures/${encodeURIComponent(input.procedureId)}/runs`, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body,
+					signal: ctrl.signal
+				});
+				if (!startResp.ok) throw await apiErrorFromResponse(startResp);
+				const { run_id } = await startResp.json();
+				inflight.current.runId = run_id;
+				const startedAt = Date.now();
+				let pollCount = 0;
+				while (true) {
+					if (ctrl.signal.aborted) return;
+					if (Date.now() - startedAt > maxWaitMs) throw new Error("procedure run timed out client-side");
+					await sleep(pollCount < 6 ? pollMs : backoffMs, ctrl.signal);
+					if (ctrl.signal.aborted) return;
+					pollCount += 1;
+					const pollResp = await fetcher(`/api/projects/${projectId}/procedures/runs/${encodeURIComponent(run_id)}`, {
+						method: "GET",
+						signal: ctrl.signal
+					});
+					if (!pollResp.ok) throw await apiErrorFromResponse(pollResp);
+					const poll = await pollResp.json();
+					if (poll.status === "running") {
+						if (poll.progress) setState((s) => ({
+							...s,
+							progress: poll.progress ?? null
 						}));
-						await sdkInstance.loadFiles(fileEntries);
+						continue;
 					}
-				} else {
-					if (!config) throw new Error("Config is required when useAsync is false. Either provide config or set useAsync=true.");
-					sdkInstance = new OxySDK(config);
-				}
-				if (mounted) {
-					setSdk(sdkInstance);
-					setIsLoading(false);
-					onReady?.(sdkInstance);
-				}
-			} catch (err) {
-				const error = err instanceof Error ? err : /* @__PURE__ */ new Error("Failed to initialize SDK");
-				if (mounted) {
-					setError(error);
-					setIsLoading(false);
-					onError?.(error);
+					if (poll.status === "done") {
+						inflight.current.runId = void 0;
+						setState({
+							state: "done",
+							progress: null,
+							result: poll.result,
+							error: null
+						});
+						return;
+					}
+					if (poll.status === "cancelled") {
+						inflight.current.runId = void 0;
+						setState({
+							state: "failed",
+							progress: null,
+							result: null,
+							error: /* @__PURE__ */ new Error("procedure cancelled")
+						});
+						return;
+					}
+					inflight.current.runId = void 0;
+					setState({
+						state: "failed",
+						progress: null,
+						result: null,
+						error: new Error(poll.error.message)
+					});
+					return;
 				}
+			} catch (e) {
+				if (e instanceof DOMException && e.name === "AbortError") return;
+				inflight.current.runId = void 0;
+				setState({
+					state: "failed",
+					progress: null,
+					result: null,
+					error: e instanceof Error ? e : new Error(String(e))
+				});
 			}
-		}
-		initializeSDK();
+		})();
+	}, [
+		projectId,
+		fetcher,
+		input.procedureId,
+		pollMs,
+		backoffMs,
+		maxWaitMs
+	]);
+	React.useEffect(() => {
 		return () => {
-			mounted = false;
-			if (sdkInstance) sdkInstance.close().catch(console.error);
+			inflight.current.abort?.abort();
 		};
+	}, []);
+	return {
+		state: state.state,
+		run,
+		cancel,
+		progress: state.progress,
+		result: state.result,
+		error: state.error
+	};
+}
+function useAgentRun(input) {
+	const { projectId, fetcher } = useOxyApp();
+	const [state, setState] = React.useState({
+		state: "idle",
+		events: [],
+		artifacts: [],
+		answer: null,
+		clarification: null,
+		threadId: null,
+		threadUrl: null,
+		error: null
+	});
+	const inflight = React.useRef({});
+	const cancel = React.useCallback(() => {
+		const runId = inflight.current.runId;
+		if (!projectId || !runId) return;
+		inflight.current.abort?.abort();
+		inflight.current.runId = void 0;
+		fetcher(`/api/projects/${projectId}/agents/asks/${encodeURIComponent(runId)}/cancel`, { method: "POST" }).catch(() => {});
+		setState((s) => ({
+			...s,
+			state: "failed",
+			error: /* @__PURE__ */ new Error("agent run cancelled by user")
+		}));
+	}, [projectId, fetcher]);
+	const ask = React.useCallback((question, opts = {}) => {
+		if (!projectId) {
+			setState((s) => ({
+				...s,
+				state: "failed",
+				error: /* @__PURE__ */ new Error("project not configured")
+			}));
+			return;
+		}
+		inflight.current.abort?.abort();
+		const ctrl = new AbortController();
+		inflight.current = { abort: ctrl };
+		setState({
+			state: "running",
+			events: [],
+			artifacts: [],
+			answer: null,
+			clarification: null,
+			threadId: opts.threadId ?? null,
+			threadUrl: opts.threadId ? `/threads/${opts.threadId}` : null,
+			error: null
+		});
+		(async () => {
+			try {
+				const body = JSON.stringify({
+					v: 1,
+					question,
+					...opts.threadId ? { thread_id: opts.threadId } : {}
+				});
+				const startResp = await fetcher(`/api/projects/${projectId}/agents/${encodeURIComponent(input.agentId)}/asks`, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body,
+					signal: ctrl.signal
+				});
+				if (!startResp.ok) throw await apiErrorFromResponse(startResp);
+				const { run_id, thread_id, thread_url } = await startResp.json();
+				inflight.current.runId = run_id;
+				setState((s) => ({
+					...s,
+					threadId: thread_id,
+					threadUrl: thread_url ?? `/threads/${thread_id}`
+				}));
+				let lastEventId = "";
+				let attempts = 0;
+				let terminated = false;
+				while (true) {
+					if (ctrl.signal.aborted) return;
+					if (terminated) return;
+					attempts += 1;
+					try {
+						await consumeSseStream({
+							url: `/api/projects/${projectId}/agents/runs/${encodeURIComponent(run_id)}/events`,
+							fetcher,
+							signal: ctrl.signal,
+							lastEventId,
+							onEvent: (ev) => {
+								if (ev.id) lastEventId = ev.id;
+								const data = parseSseData(ev.data);
+								const eventType = ev.event || "message";
+								const artifact = extractSqlArtifact(eventType, ev.id, data);
+								const token = eventType === "text_delta" && typeof data === "object" && data !== null && "token" in data ? String(data.token) : null;
+								setState((s) => ({
+									...s,
+									events: [...s.events, {
+										type: eventType,
+										data
+									}],
+									artifacts: artifact ? [...s.artifacts, artifact] : s.artifacts,
+									answer: token !== null ? (s.answer ?? "") + token : s.answer
+								}));
+								if (ev.event === "done") {
+									terminated = true;
+									inflight.current.runId = void 0;
+									setState((s) => ({
+										...s,
+										state: "done"
+									}));
+								} else if (ev.event === "failed" || ev.event === "error" || ev.event === "cancelled") {
+									terminated = true;
+									inflight.current.runId = void 0;
+									const message = typeof data === "object" && data !== null && "message" in data ? String(data.message) : `agent run ${ev.event}`;
+									setState((s) => ({
+										...s,
+										state: "failed",
+										error: new Error(message)
+									}));
+								} else if (ev.event === "ask_user") {
+									terminated = true;
+									const clarification = typeof data === "object" && data !== null && "question" in data ? String(data.question) : "Agent needs clarification.";
+									setState((s) => ({
+										...s,
+										state: "needs_clarification",
+										clarification
+									}));
+								}
+							}
+						});
+					} catch (err) {
+						if (err instanceof DOMException && err.name === "AbortError") return;
+						if (attempts >= 5) {
+							inflight.current.runId = void 0;
+							setState((s) => ({
+								...s,
+								state: "failed",
+								error: err instanceof Error ? err : new Error(String(err))
+							}));
+							return;
+						}
+					}
+					if (terminated) return;
+					await sleep(1e3, ctrl.signal);
+				}
+			} catch (e) {
+				if (e instanceof DOMException && e.name === "AbortError") return;
+				inflight.current.runId = void 0;
+				setState((s) => ({
+					...s,
+					state: "failed",
+					error: e instanceof Error ? e : new Error(String(e))
+				}));
+			}
+		})();
 	}, [
-		config,
-		useAsync,
-		onReady,
-		onError
+		projectId,
+		fetcher,
+		input.agentId
 	]);
-	const content = (() => {
-		if (isLoading && loadingFallback !== void 0) return loadingFallback;
-		if (error && errorFallback !== void 0) return typeof errorFallback === "function" ? errorFallback(error) : errorFallback;
-		return children;
-	})();
-	return /* @__PURE__ */ React.createElement(OxyContext.Provider, { value: {
-		sdk,
-		isLoading,
-		error
-	} }, content);
+	React.useEffect(() => {
+		return () => {
+			inflight.current.abort?.abort();
+		};
+	}, []);
+	return {
+		state: state.state,
+		ask,
+		cancel,
+		events: state.events,
+		artifacts: state.artifacts,
+		answer: state.answer,
+		clarification: state.clarification,
+		threadId: state.threadId,
+		threadUrl: state.threadUrl,
+		error: state.error
+	};
+}
+/** Parsed JSON payload of an SSE `data:` line, falling back to raw
+*  string on parse failure. */
+function parseSseData(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+/** UI event types in the analytics taxonomy that carry SQL the bundle
+*  may want to render alongside the answer. Each carries the same
+*  shape (`query` / `columns` / `rows` / `success`) so we can parse
+*  uniformly. New types added upstream don't surface as artifacts
+*  until added here — that's intentional, the renderer needs to
+*  know how to display each. */
+const SQL_EVENT_TYPES = new Set([
+	"query_executed",
+	"query_generated",
+	"verified_sql",
+	"semantic_query",
+	"omni_query"
+]);
+/** Extract a SQL artifact from a single SSE event when the type +
+*  payload shape match. Returns `null` for events that aren't SQL
+*  carriers or whose payload doesn't include the expected fields. */
+function extractSqlArtifact(eventType, eventId, data) {
+	if (!SQL_EVENT_TYPES.has(eventType)) return null;
+	if (typeof data !== "object" || data === null) return null;
+	const obj = data;
+	const sql = typeof obj.query === "string" ? obj.query : typeof obj.sql === "string" ? obj.sql : null;
+	if (!sql) return null;
+	const columns = Array.isArray(obj.columns) ? obj.columns.map(String) : void 0;
+	const rows = Array.isArray(obj.rows) ? obj.rows : void 0;
+	const rowCount = typeof obj.row_count === "number" ? obj.row_count : typeof obj.rowCount === "number" ? obj.rowCount : rows?.length;
+	const artifact = {
+		type: "sql",
+		id: eventId || `${eventType}-${sql.slice(0, 32)}`,
+		source: eventType,
+		sql
+	};
+	if (columns && rows) artifact.results = {
+		columns,
+		rows,
+		rowCount: rowCount ?? rows.length
+	};
+	const errMsg = typeof obj.error === "string" ? obj.error : obj.success === false && typeof obj.message === "string" ? obj.message : void 0;
+	if (errMsg) artifact.error = errMsg;
+	return artifact;
 }
 /**
-* Hook to access OxySDK from child components
-*
-* @throws {Error} If used outside of OxyProvider
-* @returns {OxyContextValue} The SDK instance, loading state, and error
-*
-* @example
-* ```tsx
-* function Dashboard() {
-*   const { sdk, isLoading, error } = useOxy();
-*
-*   useEffect(() => {
-*     if (sdk) {
-*       sdk.loadAppData('dashboard.app.yml')
-*         .then(() => sdk.query('SELECT * FROM my_table'))
-*         .then(result => console.log(result));
-*     }
-*   }, [sdk]);
+* Hand-rolled SSE consumer using `fetch` + `ReadableStream`. We use
+* this in place of `EventSource` because:
+*   1. EventSource doesn't expose the connection's `Last-Event-ID`
+*      header in a way you can control. The browser tracks it
+*      internally but you can't pass a starting value, so a hook
+*      that wants to resume after a tab switch / network blip has
+*      no way to ask the server to replay from a known point.
+*   2. EventSource can't pass `Authorization` / other custom
+*      headers — only `withCredentials` for cookies. Fine today,
+*      but couples us to cookie auth forever.
 *
-*   if (isLoading) return <div>Loading SDK...</div>;
-*   if (error) return <div>Error: {error.message}</div>;
-*   if (!sdk) return null;
+* The parser handles the message-block model from the SSE spec
+* verbatim: lines split by `\n` (or `\r\n` / `\r`), event blocks
+* separated by blank lines, `id:` / `event:` / `data:` fields
+* accumulated per block. Multiple `data:` lines concatenate with
+* `\n` (per spec) — we honor that even though the server emits
+* single-line data today.
 *
-*   return <div>Dashboard</div>;
-* }
-* ```
+* Throws on network error or non-2xx. Returns when the stream ends
+* normally (server closed connection cleanly).
 */
-function useOxy() {
-	const context = useContext(OxyContext);
-	if (context === void 0) throw new Error("useOxy must be used within an OxyProvider");
-	return context;
+async function consumeSseStream(opts) {
+	const headers = {
+		accept: "text/event-stream",
+		"cache-control": "no-cache"
+	};
+	if (opts.lastEventId) headers["Last-Event-ID"] = opts.lastEventId;
+	const resp = await opts.fetcher(opts.url, {
+		method: "GET",
+		headers,
+		signal: opts.signal
+	});
+	if (!resp.ok) throw await apiErrorFromResponse(resp);
+	if (!resp.body) throw new Error("SSE response has no body");
+	const reader = resp.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let currentId = "";
+	let currentEvent = "message";
+	let currentData = [];
+	const dispatch = () => {
+		if (currentData.length === 0 && currentEvent === "message" && !currentId) return;
+		opts.onEvent({
+			id: currentId,
+			event: currentEvent,
+			data: currentData.join("\n")
+		});
+		currentEvent = "message";
+		currentData = [];
+	};
+	while (true) {
+		const { value, done } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let nlIndex;
+		while ((nlIndex = buffer.search(/\r\n|\r|\n/)) !== -1) {
+			if (nlIndex === buffer.length - 1 && buffer[nlIndex] === "\r") break;
+			const line = buffer.slice(0, nlIndex);
+			const sep = buffer.slice(nlIndex, nlIndex + 2);
+			buffer = buffer.slice(nlIndex + (sep === "\r\n" ? 2 : 1));
+			if (line === "") {
+				dispatch();
+				continue;
+			}
+			if (line.startsWith(":")) continue;
+			const colonAt = line.indexOf(":");
+			const field = colonAt === -1 ? line : line.slice(0, colonAt);
+			let value = colonAt === -1 ? "" : line.slice(colonAt + 1);
+			if (value.startsWith(" ")) value = value.slice(1);
+			switch (field) {
+				case "id":
+					currentId = value;
+					break;
+				case "event":
+					currentEvent = value;
+					break;
+				case "data":
+					currentData.push(value);
+					break;
+			}
+		}
+	}
+	if (currentData.length > 0) dispatch();
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		const t = setTimeout(resolve, ms);
+		signal?.addEventListener("abort", () => {
+			clearTimeout(t);
+			reject(new DOMException("aborted", "AbortError"));
+		}, { once: true });
+	});
 }
 /**
-* Hook to access OxySDK that throws if not ready
+* Renders an agent run's answer + artifacts + thread link as a
+* single block. The default styling is intentionally neutral
+* (system fonts, gray surfaces) so it blends into any bundle.
 *
-* This is a convenience hook that returns the SDK directly or throws an error if not initialized.
-* Use this when you know the SDK should be ready.
+* Designed to be paired with `useAgentRun`:
 *
-* @throws {Error} If used outside of OxyProvider or if SDK is not initialized
-* @returns {OxySDK} The SDK instance
-*
-* @example
 * ```tsx
-* function DataTable() {
-*   const sdk = useOxySDK();
-*   const [data, setData] = useState(null);
-*
-*   useEffect(() => {
-*     sdk.loadFile('data.parquet', 'data')
-*       .then(() => sdk.query('SELECT * FROM data LIMIT 100'))
-*       .then(setData);
-*   }, [sdk]);
-*
-*   return <table>...</table>;
-* }
+* const run = useAgentRun({ agentId: "analyst" });
+* return (
+*   <>
+*     <button onClick={() => run.ask("how many users last week?")}>Ask</button>
+*     <OxyAnswer {...run} />
+*   </>
+* );
 * ```
 */
-function useOxySDK() {
-	const { sdk, isLoading, error } = useOxy();
-	if (error) throw error;
-	if (isLoading || !sdk) throw new Error("OxySDK is not yet initialized");
-	return sdk;
+function OxyAnswer(props) {
+	const { answer, artifacts = [], state, clarification, error, threadUrl, threadLinkLabel = "Continue this thread in Oxy", maxArtifactRows = 10, className } = props;
+	const isRunning = state === "running";
+	const isFailed = state === "failed";
+	const needsClarification = state === "needs_clarification";
+	return /* @__PURE__ */ React.createElement("div", {
+		className,
+		style: styles.answerWrap
+	}, isRunning && answer === null ? /* @__PURE__ */ React.createElement("div", { style: styles.statusRow }, /* @__PURE__ */ React.createElement("span", {
+		style: styles.spinner,
+		"aria-hidden": "true"
+	}), /* @__PURE__ */ React.createElement("span", { style: styles.statusText }, "Thinking…")) : null, artifacts.length > 0 ? /* @__PURE__ */ React.createElement("div", { style: styles.artifactList }, artifacts.map((a) => /* @__PURE__ */ React.createElement(SqlArtifactBlock, {
+		key: a.id,
+		artifact: a,
+		maxRows: maxArtifactRows
+	}))) : null, answer ? /* @__PURE__ */ React.createElement("div", { style: styles.markdown }, /* @__PURE__ */ React.createElement(MarkdownText, { text: answer })) : null, needsClarification && clarification ? /* @__PURE__ */ React.createElement("div", { style: styles.clarification }, /* @__PURE__ */ React.createElement("strong", null, "Agent needs clarification:"), /* @__PURE__ */ React.createElement("div", { style: { marginTop: 4 } }, clarification)) : null, isFailed && error ? /* @__PURE__ */ React.createElement(ErrorBlock, { error }) : null, threadUrl && (answer || artifacts.length > 0) ? /* @__PURE__ */ React.createElement("div", { style: styles.threadLinkRow }, /* @__PURE__ */ React.createElement("a", {
+		href: threadUrl,
+		target: "_blank",
+		rel: "noreferrer noopener",
+		style: styles.threadLink
+	}, threadLinkLabel, " →"), /* @__PURE__ */ React.createElement("span", {
+		style: styles.betaBadge,
+		title: "Thread linking is in beta — see docs"
+	}, "beta")) : null);
+}
+/**
+* Complete drop-in chat surface. One agent, one input, one answer
+* view. The chat is single-turn by default — each new question
+* cancels the previous run and clears the answer. Bundles that
+* want a multi-turn conversation history compose their own UI
+* using `useAgentRun` directly.
+*
+* Single-turn keeps the surface dead simple: bundles use this for
+* the "ask anything about your data" widget that sits next to
+* structured panels. Multi-turn is rare in those contexts and
+* better expressed by the bundle.
+*/
+function OxyChat(props) {
+	const { agentId, placeholder = "Ask a question about your data…", submitLabel = "Ask", emptyState, maxArtifactRows, className } = props;
+	const run = useAgentRun({ agentId });
+	const [question, setQuestion] = React.useState("");
+	const submit = React.useCallback((e) => {
+		e?.preventDefault();
+		const q = question.trim();
+		if (!q || run.state === "running") return;
+		run.ask(q);
+	}, [question, run]);
+	return /* @__PURE__ */ React.createElement("div", {
+		className,
+		style: styles.chatWrap
+	}, /* @__PURE__ */ React.createElement("form", {
+		onSubmit: submit,
+		style: styles.chatForm
+	}, /* @__PURE__ */ React.createElement("input", {
+		type: "text",
+		value: question,
+		onChange: (e) => setQuestion(e.target.value),
+		placeholder,
+		disabled: run.state === "running",
+		style: styles.chatInput,
+		"aria-label": "Question"
+	}), /* @__PURE__ */ React.createElement("button", {
+		type: "submit",
+		disabled: run.state === "running" || question.trim() === "",
+		style: styles.chatSubmit
+	}, run.state === "running" ? "…" : submitLabel), run.state === "running" ? /* @__PURE__ */ React.createElement("button", {
+		type: "button",
+		onClick: run.cancel,
+		style: styles.chatCancel
+	}, "Stop") : null), run.state === "idle" ? emptyState ?? /* @__PURE__ */ React.createElement("div", { style: styles.emptyState }, "Ask a question to get started.") : /* @__PURE__ */ React.createElement(OxyAnswer, {
+		answer: run.answer,
+		artifacts: run.artifacts,
+		state: run.state,
+		clarification: run.clarification,
+		error: run.error,
+		threadUrl: run.threadUrl,
+		maxArtifactRows
+	}));
+}
+function SqlArtifactBlock(props) {
+	const { artifact, maxRows } = props;
+	const [open, setOpen] = React.useState(false);
+	const results = artifact.results;
+	const truncated = results ? results.rows.length > maxRows : false;
+	const visibleRows = results ? results.rows.slice(0, maxRows) : [];
+	const sourceLabel = artifact.source === "verified_sql" ? "Verified query" : artifact.source === "semantic_query" ? "Semantic query" : artifact.source === "omni_query" ? "Omni query" : "Query";
+	return /* @__PURE__ */ React.createElement("div", { style: styles.artifact }, /* @__PURE__ */ React.createElement("button", {
+		type: "button",
+		onClick: () => setOpen((o) => !o),
+		style: styles.artifactHeader
+	}, /* @__PURE__ */ React.createElement("span", { style: styles.artifactBadge }, sourceLabel), /* @__PURE__ */ React.createElement("span", { style: styles.artifactSummary }, results ? `${results.rowCount} row${results.rowCount === 1 ? "" : "s"}` : artifact.error ? "execution failed" : "SQL only"), /* @__PURE__ */ React.createElement("span", { style: styles.artifactToggle }, open ? "Hide" : "Show")), open ? /* @__PURE__ */ React.createElement("div", null, /* @__PURE__ */ React.createElement("pre", { style: styles.sqlBlock }, artifact.sql), artifact.error ? /* @__PURE__ */ React.createElement("div", { style: styles.error }, artifact.error) : results ? /* @__PURE__ */ React.createElement("div", { style: styles.resultsWrap }, /* @__PURE__ */ React.createElement("table", { style: styles.resultsTable }, /* @__PURE__ */ React.createElement("thead", null, /* @__PURE__ */ React.createElement("tr", null, results.columns.map((c) => /* @__PURE__ */ React.createElement("th", {
+		key: c,
+		style: styles.resultsTh
+	}, c)))), /* @__PURE__ */ React.createElement("tbody", null, visibleRows.map((row, i) => /* @__PURE__ */ React.createElement("tr", { key: i }, row.map((cell, j) => /* @__PURE__ */ React.createElement("td", {
+		key: j,
+		style: styles.resultsTd
+	}, formatCell(cell))))))), truncated ? /* @__PURE__ */ React.createElement("div", { style: styles.truncatedNote }, "+", results.rows.length - maxRows, " more rows. Open the thread in Oxy to see all.") : null) : null) : null);
 }
+function formatCell(value) {
+	if (value === null || value === void 0) return "—";
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+}
+/**
+* Renders a thrown Error with the server's `hint` line broken out
+* if the error is an `OxyApiError`. Falls back to `error.message`
+* for plain Errors. Whitespace-preserving so multi-line hints from
+* the server land readably.
+*/
+function ErrorBlock(props) {
+	const { error } = props;
+	if (error instanceof OxyApiError) return /* @__PURE__ */ React.createElement("div", { style: styles.error }, /* @__PURE__ */ React.createElement("div", null, /* @__PURE__ */ React.createElement("strong", null, "Run failed:"), " ", error.message.split("\n\n")[0]), error.hint ? /* @__PURE__ */ React.createElement("div", { style: {
+		marginTop: 6,
+		fontWeight: 400,
+		whiteSpace: "pre-wrap"
+	} }, /* @__PURE__ */ React.createElement("strong", null, "Hint:"), " ", error.hint) : null);
+	return /* @__PURE__ */ React.createElement("div", { style: styles.error }, /* @__PURE__ */ React.createElement("strong", null, "Run failed:"), " ", error.message);
+}
+function MarkdownText(props) {
+	const blocks = React.useMemo(() => parseMarkdown(props.text), [props.text]);
+	return /* @__PURE__ */ React.createElement(React.Fragment, null, blocks);
+}
+function parseMarkdown(text) {
+	const lines = text.replace(/\r\n/g, "\n").split("\n");
+	const blocks = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		if (line === void 0) {
+			i++;
+			continue;
+		}
+		const fence = line.match(/^```(\w*)\s*$/);
+		if (fence) {
+			const lang = fence[1] ?? "";
+			const buf = [];
+			i++;
+			while (i < lines.length && !/^```\s*$/.test(lines[i] ?? "")) {
+				buf.push(lines[i] ?? "");
+				i++;
+			}
+			i++;
+			blocks.push({
+				kind: "code",
+				lang,
+				code: buf.join("\n")
+			});
+			continue;
+		}
+		const h = line.match(/^(#{1,3})\s+(.+)$/);
+		if (h) {
+			blocks.push({
+				kind: "h",
+				level: h[1]?.length,
+				text: h[2]
+			});
+			i++;
+			continue;
+		}
+		if (/^\s*[-*]\s+/.test(line)) {
+			const items = [];
+			while (i < lines.length && /^\s*[-*]\s+/.test(lines[i] ?? "")) {
+				items.push((lines[i] ?? "").replace(/^\s*[-*]\s+/, ""));
+				i++;
+			}
+			blocks.push({
+				kind: "list",
+				items
+			});
+			continue;
+		}
+		if (line.trim() === "") {
+			i++;
+			continue;
+		}
+		const buf = [line];
+		i++;
+		while (i < lines.length) {
+			const next = lines[i] ?? "";
+			if (next.trim() === "" || /^#{1,3}\s+/.test(next) || /^```/.test(next) || /^\s*[-*]\s+/.test(next)) break;
+			buf.push(next);
+			i++;
+		}
+		blocks.push({
+			kind: "p",
+			text: buf.join(" ")
+		});
+	}
+	return blocks.map((b, idx) => {
+		switch (b.kind) {
+			case "h": {
+				const Tag = `h${b.level}`;
+				const headingStyle = b.level === 1 ? styles.h1 : b.level === 2 ? styles.h2 : styles.h3;
+				return /* @__PURE__ */ React.createElement(Tag, {
+					key: idx,
+					style: headingStyle
+				}, renderInline(b.text));
+			}
+			case "code": return /* @__PURE__ */ React.createElement("pre", {
+				key: idx,
+				style: styles.codeBlock,
+				"data-lang": b.lang || void 0
+			}, /* @__PURE__ */ React.createElement("code", null, b.code));
+			case "list": return /* @__PURE__ */ React.createElement("ul", {
+				key: idx,
+				style: styles.list
+			}, b.items.map((item, i) => /* @__PURE__ */ React.createElement("li", { key: i }, renderInline(item))));
+			case "p": return /* @__PURE__ */ React.createElement("p", {
+				key: idx,
+				style: styles.paragraph
+			}, renderInline(b.text));
+		}
+	});
+}
+/**
+* Inline tokenizer for **bold**, *italic*, `code`, and [text](url).
+* Lazy: scan once, split into segments. The patterns are matched in
+* priority order (code first so backticks don't get eaten by bold).
+*/
+function renderInline(text) {
+	const segments = [];
+	let remaining = text;
+	let key = 0;
+	const patterns = [
+		{
+			re: /`([^`]+)`/,
+			render: (m) => /* @__PURE__ */ React.createElement("code", { style: styles.inlineCode }, m[1])
+		},
+		{
+			re: /\[([^\]]+)\]\(([^)]+)\)/,
+			render: (m) => {
+				if (isSafeLinkHref(m[2])) return /* @__PURE__ */ React.createElement("a", {
+					href: m[2],
+					target: "_blank",
+					rel: "noreferrer noopener",
+					style: styles.link
+				}, m[1]);
+				return /* @__PURE__ */ React.createElement(React.Fragment, null, m[1]);
+			}
+		},
+		{
+			re: /\*\*([^*]+)\*\*/,
+			render: (m) => /* @__PURE__ */ React.createElement("strong", null, m[1])
+		},
+		{
+			re: /\*([^*]+)\*/,
+			render: (m) => /* @__PURE__ */ React.createElement("em", null, m[1])
+		}
+	];
+	while (remaining.length > 0) {
+		let earliest = null;
+		for (const { re, render } of patterns) {
+			const m = re.exec(remaining);
+			if (m && (earliest === null || m.index < earliest.idx)) earliest = {
+				idx: m.index,
+				len: m[0].length,
+				node: render(m)
+			};
+		}
+		if (earliest === null) {
+			segments.push(remaining);
+			break;
+		}
+		if (earliest.idx > 0) segments.push(remaining.slice(0, earliest.idx));
+		segments.push(/* @__PURE__ */ React.createElement(React.Fragment, { key: key++ }, earliest.node));
+		remaining = remaining.slice(earliest.idx + earliest.len);
+	}
+	return segments;
+}
+const SANS = "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif";
+const MONO = "ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, monospace";
+const styles = {
+	answerWrap: {
+		fontFamily: SANS,
+		fontSize: 14,
+		lineHeight: 1.5,
+		color: "#1f2937"
+	},
+	statusRow: {
+		display: "flex",
+		alignItems: "center",
+		gap: 8,
+		padding: "8px 0"
+	},
+	spinner: {
+		display: "inline-block",
+		width: 12,
+		height: 12,
+		borderRadius: "50%",
+		border: "2px solid #d1d5db",
+		borderTopColor: "#6b7280",
+		animation: "oxy-spin 0.8s linear infinite"
+	},
+	statusText: { color: "#6b7280" },
+	markdown: { marginTop: 8 },
+	h1: {
+		fontSize: 20,
+		fontWeight: 600,
+		margin: "16px 0 8px"
+	},
+	h2: {
+		fontSize: 17,
+		fontWeight: 600,
+		margin: "14px 0 6px"
+	},
+	h3: {
+		fontSize: 15,
+		fontWeight: 600,
+		margin: "12px 0 4px"
+	},
+	paragraph: { margin: "0 0 8px" },
+	list: {
+		margin: "0 0 8px",
+		paddingLeft: 20
+	},
+	codeBlock: {
+		fontFamily: MONO,
+		fontSize: 12,
+		background: "#f3f4f6",
+		border: "1px solid #e5e7eb",
+		borderRadius: 6,
+		padding: "8px 10px",
+		overflowX: "auto",
+		margin: "8px 0"
+	},
+	inlineCode: {
+		fontFamily: MONO,
+		fontSize: "0.92em",
+		background: "#f3f4f6",
+		padding: "1px 4px",
+		borderRadius: 3
+	},
+	link: {
+		color: "#2563eb",
+		textDecoration: "underline"
+	},
+	clarification: {
+		marginTop: 12,
+		padding: "10px 12px",
+		background: "#fef3c7",
+		border: "1px solid #fcd34d",
+		borderRadius: 6,
+		color: "#78350f"
+	},
+	error: {
+		marginTop: 12,
+		padding: "10px 12px",
+		background: "#fee2e2",
+		border: "1px solid #fca5a5",
+		borderRadius: 6,
+		color: "#991b1b"
+	},
+	threadLinkRow: {
+		marginTop: 12,
+		textAlign: "right",
+		display: "flex",
+		justifyContent: "flex-end",
+		alignItems: "center",
+		gap: 6
+	},
+	threadLink: {
+		fontSize: 12,
+		color: "#6b7280",
+		textDecoration: "none"
+	},
+	betaBadge: {
+		fontSize: 9,
+		fontWeight: 600,
+		letterSpacing: .5,
+		textTransform: "uppercase",
+		padding: "1px 5px",
+		borderRadius: 3,
+		background: "#fef3c7",
+		color: "#92400e",
+		border: "1px solid #fcd34d"
+	},
+	artifactList: {
+		display: "flex",
+		flexDirection: "column",
+		gap: 8,
+		marginBottom: 8
+	},
+	artifact: {
+		border: "1px solid #e5e7eb",
+		borderRadius: 6,
+		background: "#fafafa",
+		overflow: "hidden"
+	},
+	artifactHeader: {
+		display: "flex",
+		alignItems: "center",
+		gap: 10,
+		width: "100%",
+		padding: "6px 10px",
+		background: "transparent",
+		border: "none",
+		borderBottom: "1px solid transparent",
+		cursor: "pointer",
+		fontFamily: SANS,
+		fontSize: 12,
+		color: "#374151"
+	},
+	artifactBadge: {
+		fontWeight: 600,
+		fontSize: 11,
+		textTransform: "uppercase",
+		letterSpacing: .4,
+		color: "#4b5563"
+	},
+	artifactSummary: {
+		color: "#6b7280",
+		flex: 1
+	},
+	artifactToggle: { color: "#2563eb" },
+	sqlBlock: {
+		fontFamily: MONO,
+		fontSize: 12,
+		margin: 0,
+		padding: "8px 10px",
+		background: "#0f172a",
+		color: "#e2e8f0",
+		overflowX: "auto"
+	},
+	resultsWrap: {
+		padding: 8,
+		overflowX: "auto"
+	},
+	resultsTable: {
+		width: "100%",
+		borderCollapse: "collapse",
+		fontSize: 12
+	},
+	resultsTh: {
+		textAlign: "left",
+		padding: "4px 8px",
+		borderBottom: "1px solid #e5e7eb",
+		fontWeight: 600,
+		color: "#374151"
+	},
+	resultsTd: {
+		padding: "4px 8px",
+		borderBottom: "1px solid #f3f4f6",
+		color: "#1f2937"
+	},
+	truncatedNote: {
+		fontSize: 11,
+		color: "#6b7280",
+		padding: "6px 8px"
+	},
+	chatWrap: {
+		fontFamily: SANS,
+		fontSize: 14,
+		color: "#1f2937"
+	},
+	chatForm: {
+		display: "flex",
+		gap: 8,
+		marginBottom: 12
+	},
+	chatInput: {
+		flex: 1,
+		padding: "8px 12px",
+		border: "1px solid #d1d5db",
+		borderRadius: 6,
+		fontSize: 14,
+		fontFamily: SANS
+	},
+	chatSubmit: {
+		padding: "8px 16px",
+		border: "none",
+		borderRadius: 6,
+		background: "#2563eb",
+		color: "#ffffff",
+		fontSize: 14,
+		fontWeight: 500,
+		cursor: "pointer"
+	},
+	chatCancel: {
+		padding: "8px 12px",
+		border: "1px solid #d1d5db",
+		borderRadius: 6,
+		background: "#ffffff",
+		color: "#374151",
+		fontSize: 14,
+		cursor: "pointer"
+	},
+	emptyState: {
+		padding: "12px 0",
+		color: "#9ca3af",
+		fontStyle: "italic"
+	}
+};
 
 //#endregion
-export { OxyClient, OxyProvider, OxySDK, ParquetReader, PostMessageAuthInvalidOriginError, PostMessageAuthInvalidResponseError, PostMessageAuthNotInIframeError, PostMessageAuthTimeoutError, createConfig, createConfigAsync, initializeDuckDB, isInIframe, queryParquet, readParquet, requestAuthFromParent, useOxy, useOxySDK };
+export { OxyAnswer, OxyApiError, OxyAppProvider, OxyChat, _resetCustomerAppManifestCacheForTest, getCustomerAppDebug, getOxyAppLogger, interpretCustomerAppError, loadCustomerAppManifest, readInjectedAppConfig, setOxyAppLogger, useAgentRun, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery };
 //# sourceMappingURL=index.mjs.map