@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/integrations/read-only-postgres-query.js

@@ -0,0 +1,164 @@
+import { loadModule, parseSync } from "libpg-query";
+import { LakebasePlugin, PostgresPlugin, SnowflakePostgresPlugin, } from "@superblocksteam/shared";
+const POSTGRES_PLUGIN_IDS = new Set([
+    LakebasePlugin.id,
+    PostgresPlugin.id,
+    SnowflakePostgresPlugin.id,
+]);
+const READ_STATEMENT_KEYS = new Set([
+    "SelectStmt",
+    "VariableShowStmt",
+]);
+const MUTATION_STATEMENT_KEYS = new Set([
+    "DeleteStmt",
+    "InsertStmt",
+    "MergeStmt",
+    "UpdateStmt",
+]);
+const FORBIDDEN_NESTED_KEYS = new Set([
+    ...MUTATION_STATEMENT_KEYS,
+    "TypeCast",
+    "intoClause",
+    "lockingClause",
+]);
+const READ_ONLY_FUNCTION_NAMES = new Set([
+    "avg",
+    "count",
+    "max",
+    "min",
+    "sum",
+]);
+const MAX_AST_DEPTH = 1_000;
+let parserReady;
+function ensureParserLoaded() {
+    parserReady ??= loadModule().catch((error) => {
+        parserReady = undefined;
+        throw error;
+    });
+    return parserReady;
+}
+function carriesValue(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    return Array.isArray(value) ? value.length > 0 : true;
+}
+function containsKey(node, keys, depth = 0) {
+    if (depth > MAX_AST_DEPTH) {
+        throw new Error("SQL parse tree exceeds the safety limit");
+    }
+    if (Array.isArray(node)) {
+        return node.some((child) => containsKey(child, keys, depth + 1));
+    }
+    if (node === null || typeof node !== "object") {
+        return false;
+    }
+    return Object.entries(node).some(([key, value]) => (keys.has(key) && carriesValue(value)) ||
+        containsKey(value, keys, depth + 1));
+}
+function nodeField(node, key) {
+    if (node === null || typeof node !== "object") {
+        return undefined;
+    }
+    const value = Reflect.get(node, key);
+    return value !== null && typeof value === "object" ? value : undefined;
+}
+function stringNodeValue(node) {
+    const stringNode = nodeField(node, "String");
+    if (!stringNode) {
+        return undefined;
+    }
+    const value = Reflect.get(stringNode, "sval");
+    return typeof value === "string" ? value : undefined;
+}
+function isAllowedReadFunction(call) {
+    const funcname = Reflect.get(call, "funcname");
+    if (!Array.isArray(funcname)) {
+        return false;
+    }
+    const names = [];
+    for (const part of funcname) {
+        const name = stringNodeValue(part);
+        if (name === undefined) {
+            return false;
+        }
+        names.push(name);
+    }
+    const functionName = names.at(-1)?.toLowerCase();
+    if (functionName === undefined) {
+        return false;
+    }
+    if (names.length > 1 &&
+        !(names.length === 2 && names[0]?.toLowerCase() === "pg_catalog")) {
+        return false;
+    }
+    return READ_ONLY_FUNCTION_NAMES.has(functionName);
+}
+function containsUnsupportedFunction(node, depth = 0) {
+    if (depth > MAX_AST_DEPTH) {
+        throw new Error("SQL parse tree exceeds the safety limit");
+    }
+    if (Array.isArray(node)) {
+        return node.some((child) => containsUnsupportedFunction(child, depth + 1));
+    }
+    if (node === null || typeof node !== "object") {
+        return false;
+    }
+    const functionCall = nodeField(node, "FuncCall");
+    if (functionCall && !isAllowedReadFunction(functionCall)) {
+        return true;
+    }
+    return Object.values(node).some((child) => containsUnsupportedFunction(child, depth + 1));
+}
+function explainRunsStatement(explain) {
+    const options = Reflect.get(explain, "options");
+    return (Array.isArray(options) &&
+        options.some((option) => {
+            const element = nodeField(option, "DefElem");
+            return element && Reflect.get(element, "defname") === "analyze";
+        }));
+}
+function isReadOnlyStatement(statement) {
+    const [statementKey] = Object.keys(statement);
+    if (statementKey === undefined) {
+        return false;
+    }
+    if (statementKey === "ExplainStmt") {
+        const explain = nodeField(statement, statementKey);
+        if (explain === undefined) {
+            return false;
+        }
+        if (!explainRunsStatement(explain)) {
+            return true;
+        }
+        const explained = nodeField(explain, "query");
+        return explained !== undefined && isReadOnlyStatement(explained);
+    }
+    return (READ_STATEMENT_KEYS.has(statementKey) &&
+        !containsKey(statement, FORBIDDEN_NESTED_KEYS) &&
+        !containsUnsupportedFunction(statement));
+}
+function extractSingleStatement(parsed) {
+    if (parsed === null || typeof parsed !== "object" || !("stmts" in parsed)) {
+        return undefined;
+    }
+    const { stmts } = parsed;
+    if (!Array.isArray(stmts) || stmts.length !== 1) {
+        return undefined;
+    }
+    return nodeField(stmts[0], "stmt");
+}
+export function supportsReadOnlyPostgresQuery(pluginId) {
+    return POSTGRES_PLUGIN_IDS.has(pluginId);
+}
+export async function isReadOnlyPostgresQuery(query) {
+    try {
+        await ensureParserLoaded();
+        const statement = extractSingleStatement(parseSync(query));
+        return statement !== undefined && isReadOnlyStatement(statement);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=read-only-postgres-query.js.map

package/dist/integrations/read-only-postgres-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only-postgres-query.js","sourceRoot":"","sources":["../../src/integrations/read-only-postgres-query.ts"],"names":[],"mappings":"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"}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+console.error("This process speaks MCP over stdio as the Superblocks CLI user. Run: superblocks mcp serve");
+process.exit(1);
+export {};
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,CAAC,KAAK,CACX,4FAA4F,CAC7F,CAAC;AACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}

package/dist/orchestrator/client.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Thin HTTP client for the Superblocks orchestrator / agent used by Gateway
+ * when Clark asks the editor peer to run APIs or load integration metadata.
+ *
+ * The base URL is discovered per session from Server `/users/me` agents
+ * (same filters as the browser), not operator-picked env. Scoped JWTs travel
+ * in `x-superblocks-authorization`, matching the editor's execute path.
+ */
+export declare class OrchestratorHttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Credential identifying who is asking, sent as `Authorization`.
+ *
+ * The orchestrator forwards this header verbatim when it fetches the app's
+ * code bundle from the Superblocks server, and that route authenticates it in
+ * its own right: a Superblocks JWT presented there is checked against
+ * `apps:view`, which a live-edit session's `apps:update` token does not carry.
+ * Sending the API key instead mirrors the browser editor, which puts its user
+ * session token here and keeps the scoped JWT to
+ * `x-superblocks-authorization`.
+ */
+type RequesterCredential = {
+    apiKey?: string;
+};
+export type SdkApiV3ExecuteInput = RequesterCredential & {
+    applicationId: string;
+    branchName?: string;
+    entryPoint: string;
+    exportName?: string;
+    inputs: Record<string, unknown>;
+    profileKey?: string;
+    scopedToken: string;
+};
+export type V2ExecuteInput = RequesterCredential & {
+    body: Record<string, unknown>;
+    profileKey?: string;
+    scopedToken: string;
+};
+export type MetadataInput = RequesterCredential & {
+    integrationId: string;
+    profileKey: string;
+    scopedToken: string;
+    stepConfiguration?: Record<string, unknown>;
+};
+export type OrchestratorClient = {
+    executeSdkApiV3(input: SdkApiV3ExecuteInput): Promise<unknown>;
+    executeV2Api(input: V2ExecuteInput): Promise<unknown>;
+    getMetadata(input: MetadataInput): Promise<Record<string, unknown>>;
+};
+export declare class HttpOrchestratorClient implements OrchestratorClient {
+    private readonly orchestratorUrl;
+    private readonly timeoutMs;
+    constructor(orchestratorUrl: string, timeoutMs?: number);
+    private baseUrl;
+    private post;
+    executeSdkApiV3(input: SdkApiV3ExecuteInput): Promise<unknown>;
+    executeV2Api(input: V2ExecuteInput): Promise<unknown>;
+    getMetadata(input: MetadataInput): Promise<Record<string, unknown>>;
+}
+export {};

package/dist/orchestrator/client.js

@@ -0,0 +1,160 @@
+/**
+ * Thin HTTP client for the Superblocks orchestrator / agent used by Gateway
+ * when Clark asks the editor peer to run APIs or load integration metadata.
+ *
+ * The base URL is discovered per session from Server `/users/me` agents
+ * (same filters as the browser), not operator-picked env. Scoped JWTs travel
+ * in `x-superblocks-authorization`, matching the editor's execute path.
+ */
+const SUPERBLOCKS_AUTHORIZATION_HEADER = "x-superblocks-authorization";
+/** Protobuf `api.v1.ViewMode.EDIT` — same numeric the UI sends on v3/execute. */
+const ORCHESTRATOR_VIEW_MODE_EDIT = 1;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_DETAIL_LENGTH = 300;
+function detailSuffix(body) {
+    if (!body.trim()) {
+        return "";
+    }
+    let detail = body;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            const record = parsed;
+            const message = record.responseMeta?.message ?? record.message ?? record.error;
+            if (typeof message === "string" && message.trim()) {
+                detail = message;
+            }
+        }
+    }
+    catch {
+        // Not JSON — fall back to the raw body.
+    }
+    return ` — ${detail.trim().slice(0, MAX_DETAIL_LENGTH)}`;
+}
+export class OrchestratorHttpError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "OrchestratorHttpError";
+    }
+}
+export class HttpOrchestratorClient {
+    orchestratorUrl;
+    timeoutMs;
+    constructor(orchestratorUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.orchestratorUrl = orchestratorUrl;
+        this.timeoutMs = timeoutMs;
+    }
+    baseUrl() {
+        return this.orchestratorUrl.replace(/\/$/, "");
+    }
+    async post(path, input) {
+        const url = new URL(`${this.baseUrl()}/${path.replace(/^\//, "")}`);
+        for (const [key, value] of Object.entries(input.query ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        const headers = new Headers({
+            Authorization: `Bearer ${input.apiKey ?? input.scopedToken}`,
+            "Content-Type": "application/json",
+            [SUPERBLOCKS_AUTHORIZATION_HEADER]: `Bearer ${input.scopedToken}`,
+        });
+        if (input.profileKey) {
+            headers.set("x-superblocks-profile", input.profileKey);
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                body: JSON.stringify(input.body),
+                headers,
+                method: "POST",
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error(`Orchestrator ${path} timed out after ${this.timeoutMs}ms`);
+            }
+            throw error;
+        }
+        if (!response.ok) {
+            if (response.status === 401) {
+                console.warn("gateway orchestrator auth rejected", {
+                    path,
+                    profileKey: input.profileKey,
+                    status: response.status,
+                });
+            }
+            throw new OrchestratorHttpError(`Orchestrator ${path} failed: ${response.status}${detailSuffix(await response.text().catch(() => ""))}`, response.status);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        const text = await response.text();
+        if (!text.trim()) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    async executeSdkApiV3(input) {
+        return this.post("v3/execute", {
+            apiKey: input.apiKey,
+            body: {
+                applicationId: input.applicationId,
+                entryPoint: input.entryPoint,
+                inputs: input.inputs,
+                viewMode: ORCHESTRATOR_VIEW_MODE_EDIT,
+                ...(input.exportName ? { exportName: input.exportName } : {}),
+                ...(input.branchName ? { branchName: input.branchName } : {}),
+                ...(input.profileKey
+                    ? {
+                        profile: {
+                            key: input.profileKey,
+                            name: input.profileKey,
+                        },
+                    }
+                    : {}),
+            },
+            profileKey: input.profileKey,
+            scopedToken: input.scopedToken,
+        });
+    }
+    async executeV2Api(input) {
+        return this.post("v2/execute", {
+            apiKey: input.apiKey,
+            body: input.body,
+            profileKey: input.profileKey,
+            query: {
+                eventType: "ON_CLARK_REQUEST",
+                viewMode: "editor",
+            },
+            scopedToken: input.scopedToken,
+        });
+    }
+    async getMetadata(input) {
+        const raw = await this.post("v2/metadata", {
+            apiKey: input.apiKey,
+            body: {
+                integration: input.integrationId,
+                profile: { name: input.profileKey },
+                stepConfiguration: input.stepConfiguration ?? {},
+            },
+            profileKey: input.profileKey,
+            scopedToken: input.scopedToken,
+        });
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            const record = raw;
+            if (record.data && typeof record.data === "object") {
+                return record.data;
+            }
+            return raw;
+        }
+        return {};
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/orchestrator/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/orchestrator/client.ts"],"names":[],"mappings":"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"}

package/dist/playwright/ensure-chromium.d.ts

@@ -0,0 +1,24 @@
+export type EnsurePlaywrightChromiumOptions = {
+    /** Override for tests. Defaults to Playwright's Chromium executable path. */
+    chromiumExecutablePath?: string;
+};
+export type EnsurePlaywrightChromiumResult = {
+    /** True when this call ran an install. */
+    installed: boolean;
+};
+/**
+ * Probe only: true when Playwright Chromium is already on disk. Does not
+ * download anything. Used by `mcp setup` capture.mode and by capabilities
+ * that must fail closed instead of waiting on `chromium.launch()`.
+ */
+export declare function playwrightChromiumPresent(options?: Pick<EnsurePlaywrightChromiumOptions, "chromiumExecutablePath">): Promise<boolean>;
+/**
+ * Ensures Playwright Chromium is on disk. Intended for
+ * `mcp setup --with-screenshots`, not every `mcp serve` - corp laptops need a
+ * one-time download with network.
+ */
+export declare function ensurePlaywrightChromium(options?: EnsurePlaywrightChromiumOptions): Promise<EnsurePlaywrightChromiumResult>;
+/**
+ * Clear error for `mcp serve` when setup was skipped.
+ */
+export declare function assertPlaywrightChromiumInstalled(options?: Pick<EnsurePlaywrightChromiumOptions, "chromiumExecutablePath">): Promise<void>;

package/dist/playwright/ensure-chromium.js

@@ -0,0 +1,60 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { chromium } from "playwright";
+const execFile = promisify(execFileCallback);
+const require = createRequire(import.meta.url);
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probe only: true when Playwright Chromium is already on disk. Does not
+ * download anything. Used by `mcp setup` capture.mode and by capabilities
+ * that must fail closed instead of waiting on `chromium.launch()`.
+ */
+export async function playwrightChromiumPresent(options = {}) {
+    const executablePath = options.chromiumExecutablePath ?? chromium.executablePath();
+    return pathExists(executablePath);
+}
+/**
+ * Ensures Playwright Chromium is on disk. Intended for
+ * `mcp setup --with-screenshots`, not every `mcp serve` - corp laptops need a
+ * one-time download with network.
+ */
+export async function ensurePlaywrightChromium(options = {}) {
+    const executablePath = options.chromiumExecutablePath ?? chromium.executablePath();
+    if (await pathExists(executablePath)) {
+        return { installed: false };
+    }
+    const playwrightCli = join(dirname(require.resolve("playwright")), "cli.js");
+    try {
+        await execFile(process.execPath, [playwrightCli, "install", "chromium"]);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to install Playwright Chromium (needed for preview screenshots). The bundled playwright install chromium command failed. Re-run: superblocks mcp setup --with-screenshots. (${detail})`);
+    }
+    if (!(await pathExists(executablePath))) {
+        throw new Error(`Playwright Chromium is still missing after install at ${executablePath}. Run: superblocks mcp setup --with-screenshots`);
+    }
+    return { installed: true };
+}
+/**
+ * Clear error for `mcp serve` when setup was skipped.
+ */
+export async function assertPlaywrightChromiumInstalled(options = {}) {
+    const executablePath = options.chromiumExecutablePath ?? chromium.executablePath();
+    if (await pathExists(executablePath)) {
+        return;
+    }
+    throw new Error(`Playwright Chromium is not installed (looked for ${executablePath}). Run: superblocks mcp setup --with-screenshots`);
+}
+//# sourceMappingURL=ensure-chromium.js.map

package/dist/playwright/ensure-chromium.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-chromium.js","sourceRoot":"","sources":["../../src/playwright/ensure-chromium.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,QAAQ,GAAG,SAAS,CAAC,gBAAgB,CAAC,CAAC;AAC7C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAY/C,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,UAA2E,EAAE;IAE7E,MAAM,cAAc,GAClB,OAAO,CAAC,sBAAsB,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;IAC9D,OAAO,UAAU,CAAC,cAAc,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,UAA2C,EAAE;IAE7C,MAAM,cAAc,GAClB,OAAO,CAAC,sBAAsB,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;IAC9D,IAAI,MAAM,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAE7E,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAC3E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,sLAAsL,MAAM,GAAG,CAChM,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,yDAAyD,cAAc,iDAAiD,CACzH,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,UAA2E,EAAE;IAE7E,MAAM,cAAc,GAClB,OAAO,CAAC,sBAAsB,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;IAC9D,IAAI,MAAM,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACrC,OAAO;IACT,CAAC;IACD,MAAM,IAAI,KAAK,CACb,oDAAoD,cAAc,kDAAkD,CACrH,CAAC;AACJ,CAAC"}

package/dist/preview/capture-screenshot.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Headless capture of a preview viewer URL for MCP image content.
+ *
+ * Best-effort: callers must succeed with URLs alone when this returns
+ * undefined. Output is capped for Claude Desktop tool-result size limits.
+ */
+export type PreviewScreenshot = {
+    dataBase64: string;
+    mimeType: "image/jpeg";
+};
+/** Soft cap on decoded bytes before base64 (~256 KiB). */
+export declare const PREVIEW_SCREENSHOT_MAX_BYTES: number;
+export type CapturePreviewScreenshot = (input: {
+    /**
+     * App-scoped bearer handed to the embed shell. Without it the shell falls
+     * back to Auth0 silent login, which has no session to find headless.
+     */
+    embedToken?: string;
+    /**
+     * The origin {@link embedToken} belongs to - the control plane the session
+     * signed in to, which already receives this token on every API call. It is
+     * the only non-loopback origin allowed to be handed the token; unset means
+     * loopback only.
+     */
+    trustedOrigin?: string;
+    url: string;
+    timeoutMs?: number;
+}) => Promise<PreviewScreenshot | undefined>;
+/**
+ * Whether a session bearer may be delivered to the page at `url`.
+ *
+ * Loopback is the user's own machine. The only remote origin allowed is the
+ * one the token was issued by, over https, so the token never reaches a host
+ * that does not already hold it.
+ */
+export declare function isTrustedEmbedOrigin(url: string, trustedOrigin?: string): boolean;
+/**
+ * Page source that hands the deployed shell its bearer, and the whole reason a
+ * headless capture can paint a real app.
+ *
+ * `ui-deployed-shell` only accepts a bearer through an `INITIALIZE_EMBED`
+ * message from its embedder, and ~300ms after mount it gives up and tries
+ * Auth0 silent login instead — which has no session to find here. At top level
+ * the shell's embedder port has no parent window to check messages against, so
+ * it accepts one posted by the page itself.
+ *
+ * Delivery happens exactly once: each `INITIALIZE_EMBED` replaces the shell's
+ * auth state and restarts its bootstrap, so a repeating handshake would keep
+ * the app from ever settling.
+ *
+ * This is source text rather than a function handed to `addInitScript` because
+ * Playwright ships a function by serializing it, which drags in whatever
+ * helpers the bundler injected into its body (`__name` under tsx) and throws a
+ * ReferenceError in the page.
+ *
+ * The result is only ever evaluated as script source (Playwright forwards it
+ * to CDP `addScriptToEvaluateOnNewDocument`), never interpolated into HTML, so
+ * `JSON.stringify` is sufficient to contain the token. Putting it in a
+ * `<script>` element would not be — the token would need `</script>` escaped.
+ */
+export declare function buildEmbedHandshakeScript(token: string, expectedOrigin: string): string;
+/**
+ * Captures a JPEG screenshot via Playwright when available. Soft-fails when
+ * Chromium is missing or the page never becomes ready — callers must still
+ * return preview URLs when this returns undefined.
+ */
+export declare const capturePreviewScreenshotWithPlaywright: CapturePreviewScreenshot;