Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

103 KB
Raw Blame
import { PLUGIN_AI_TASKS } from "./pluginAiCompletion";
import type { PluginAiProvider, PluginAiModel, PluginAiGenerateRequest, PluginAiStreamRequest, PluginAiStreamChunkEvent, PluginAiTask } from "./pluginAiCompletion";
import type { InstalledPlugin, PluginBinaryEvent, PluginEvent, PluginUiAssetPayload, PluginUiContribution } from "@/types/database";
import { clonePluginData, snapshotPluginWorkbenchContext } from "./pluginData";
import { MAX_PLUGIN_PLAN_SQL_CHARS, MAX_PLUGIN_PLAN_TIMEOUT_MS, PLUGIN_PLAN_PERMISSION, type PluginPlanCapabilities, type PluginPlanRequest, type PluginPlanResult } from "@/types/pluginPlan";
import { createPluginAiConversation, type AiPluginConversationRequest } from "@/lib/ai/aiPluginConversation";
import { isValidPluginAiRecommendationTemplate, resolvePluginAiRecommendationUpdate, type PluginAiRecommendationContext, type PluginAiRecommendationUpdate } from "@/lib/plugins/pluginAiRecommendations";
import type { PluginAiRecommendation } from "@/types/pluginAiRecommendations";
import { MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS, PLUGIN_SCHEMA_METADATA_CAPABILITY, PLUGIN_SCHEMA_METADATA_PERMISSION, type PluginTableContext, type PluginTableMetadata } from "@/types/pluginSchemaMetadata";
import { MAX_PLUGIN_DATA_MAX_ROWS, MAX_PLUGIN_DATA_NAME_CHARS, MAX_PLUGIN_DATA_SQL_CHARS, MAX_PLUGIN_DATA_TIMEOUT_MS, PLUGIN_DATA_ACCESS_NOT_GRANTED, PLUGIN_DATA_CAPABILITY, PLUGIN_DATA_READ_PERMISSION, type PluginDataQueryRequest, type PluginDataQueryResult } from "@/types/pluginData";
import { PLUGIN_CONNECTIONS_CAPABILITY, PLUGIN_CONNECTIONS_READ_PERMISSION, type PluginConnectionSummary } from "@/types/pluginConnection";
import { floatingWindowLabel } from "@/lib/app/windowContext";
import { parseFloatingWindowRequest, type FloatingRect, type OpenFloatingWindowRequest, type OpenFloatingWindowResult } from "@/lib/plugins/pluginFloatingWindow";

const PLUGIN_MESSAGE_SOURCE = "dbx-plugin";
const HOST_MESSAGE_SOURCE = "dbx-host";
const BRIDGE_VERSION = 1;
const MAX_BRIDGE_PAYLOAD_BYTES = 2 * 1024 * 1024;
const MAX_BRIDGE_BINARY_BYTES = 8 * 1024 * 1024;
const MAX_CLIPBOARD_IMAGE_BASE64_BYTES = 24 * 1024 * 1024;
// Distinct from the sidecar binary cap: saved files go straight from the
// plugin iframe to disk and never traverse plugin frames.
const MAX_BRIDGE_SAVE_BYTES = 512 * 1024 * 1024;
// Mirrors MAX_PLUGIN_PLAN_NAME_CHARS in crates/dbx-core/src/query/plugin_plan.rs.
const MAX_PLUGIN_PLAN_IDENTIFIER_CHARS = 256;
/**
 * In-flight `host.queryData` calls per bridge. Plugin queries share the
 * connection pool with the user's own tabs, so a runaway plugin must not be
 * able to occupy it.
 */
export const MAX_CONCURRENT_PLUGIN_DATA_QUERIES = 4;

// Clipboard reads are the one permission that hands environment data (the
// system clipboard) to plugin code with no user interaction on each call, so
// beyond the manifest permission gate the bridge adds: a per-session consent
// prompt before the first read, a bounded audit trail, and a read-rate cap.
// A plugin that trips the cap waits rather than being able to silently poll.
export const PLUGIN_CLIPBOARD_READ_MIN_INTERVAL_MS = 1_000;
export const PLUGIN_CLIPBOARD_AUDIT_CAPACITY = 200;

export interface PluginClipboardAuditEntry {
  at: number;
  /** Request outcome: granted (content returned), denied (user or no consent surface). */
  outcome: "granted" | "denied" | "rate-limited";
  /** Returned payload size (text code units or decoded image bytes); content is never stored. */
  length: number;
}

export interface PluginClipboardReadGateState {
  /** Consent for the current bridge lifetime; null = never asked. */
  consented: boolean | null;
  lastReadAt: number;
  audit: PluginClipboardAuditEntry[];
}

export function createClipboardReadGate(): PluginClipboardReadGateState {
  return { consented: null, lastReadAt: 0, audit: [] };
}

/**
 * Rate gate: at most one read per PLUGIN_CLIPBOARD_READ_MIN_INTERVAL_MS.
 * Returns true when the read may proceed; a denied (rate-limited) read is
 * recorded by the caller.
 */
export function clipboardReadGateAllows(state: PluginClipboardReadGateState, now: number): boolean {
  return state.lastReadAt <= 0 || now - state.lastReadAt >= PLUGIN_CLIPBOARD_READ_MIN_INTERVAL_MS;
}

export function recordClipboardRead(state: PluginClipboardReadGateState, now: number, outcome: PluginClipboardAuditEntry["outcome"], length: number): void {
  if (outcome !== "rate-limited") state.lastReadAt = now;
  state.audit.push({ at: now, outcome, length });
  if (state.audit.length > PLUGIN_CLIPBOARD_AUDIT_CAPACITY) state.audit.splice(0, state.audit.length - PLUGIN_CLIPBOARD_AUDIT_CAPACITY);
}

/** Structured editor appearance: SQL editor settings that have no CSS-token
 * carrier (font size is a number, the syntax theme an id). Font families are
 * additionally mirrored as `--font-sans` / `--font-mono` root tokens. */
export interface PluginEditorAppearance {
  fontFamily: string;
  fontSize: number;
  theme: string;
}

export interface PluginBridgeTheme {
  appearance: "light" | "dark";
  /** Resolved DBX design tokens (`--color-*`, `--radius-*`, `--font-*`, ...) for the current theme. */
  tokens: Record<string, string>;
  /** Editor appearance snapshot. Optional: older in-flight snapshots omit it. */
  editor?: PluginEditorAppearance;
}

export interface PluginWorkbenchContext {
  connectionId?: string;
  database?: string;
  schema?: string;
  values?: Record<string, unknown>;
  [key: string]: unknown;
}

export interface PluginClipboardImage {
  contentType: "image/png";
  dataBase64: string;
  width: number;
  height: number;
}

export interface PluginSaveFileRequest {
  fileName?: string;
  contentType?: string;
}

export interface PluginSaveFileResult {
  path: string;
}

export interface PluginDownloadRequest extends PluginSaveFileRequest {
  downloadId: string;
  params: Record<string, unknown>;
}

/** An opened local-file handle handed to a plugin for streaming transfer. */
export interface PluginFileHandleMeta {
  handleId: string;
  name: string;
  size: number;
  contentType: string;
  /** Only for files expanded out of a dropped folder: '/'-separated path relative to the dropped folder root, so the plugin can rebuild the dragged tree. */
  relativePath?: string;
}

export interface PluginDragPosition {
  x: number;
  y: number;
}

export interface PluginPickFilesOptions {
  multiple?: boolean;
}

export interface PluginFileReadChunk {
  dataBase64: string;
  length: number;
  eof: boolean;
}

export interface PluginFileWriteResult {
  written: number;
  nextOffset: number;
}

/** Chunk size the host advertises for streamed saves; fits the bridge payload cap after base64. */
export const PLUGIN_SAVE_CHUNK_BYTES = 1024 * 1024;

/**
 * Per-value cap for `host.storage` entries. The whole store is additionally
 * capped by the native host; both bounds keep this a UI-state store — bulk
 * data belongs to the sidecar's data directory.
 */
export const MAX_PLUGIN_STORAGE_VALUE_BYTES = 256 * 1024;
/** Longest accepted `host.storage` key, mirroring the native host's bound. */
export const MAX_PLUGIN_STORAGE_KEY_CHARS = 256;

export interface PluginHostBridgeApi {
  invoke<T = unknown>(pluginId: string, method: string, params?: unknown, timeoutMs?: number): Promise<T>;
  notify(pluginId: string, method: string, params?: unknown): Promise<void>;
  sendBinary(pluginId: string, channel: string, dataBase64: string): Promise<void>;
  readAsset(pluginId: string, path: string): Promise<PluginUiAssetPayload>;
  listAiProviders?(): Promise<PluginAiProvider[]>;
  discoverAiModels?(configId: string): Promise<PluginAiModel[]>;
  listAiModels?(): Promise<PluginAiModel[]>;
  /** Must obtain trusted host consent for every send; never return provider errors or credentials. */
  generateAiText?(pluginName: string, input: PluginAiGenerateRequest): Promise<string>;
  /**
   * E1 incremental generation: chunks ride `host.ai.generationChunk` events
   * scoped to the request's requestId (the same pattern as
   * `host.download.progress`); the promise resolves with the full text once
   * the stream completes. Must go through the same host consent as the plain
   * call.
   */
  generateAiTextStream?(pluginName: string, request: PluginAiStreamRequest, onChunk: (chunk: PluginAiStreamChunkEvent) => void): Promise<string>;
  /** Cancels one active streamed generation of THIS bridge by requestId. */
  cancelAiGeneration?(requestId: string): Promise<boolean>;
  openAiConversation?(request: AiPluginConversationRequest): Promise<void>;
  setAiRecommendations?(update: PluginAiRecommendationHostUpdate): void;
  openWorkbench?(pluginId: string, contributionId: string, context?: PluginWorkbenchContext, options?: { forceNew?: boolean; target?: "tab" }): Promise<void> | void;
  /**
   * Updates the calling workbench tab/dock title (or resets to default when title is null).
   * Scoped to the single surface hosting the caller.
   */
  setTitle?(title: string | null): Promise<void> | void;
  /** Reads the calling workbench tab/dock title. */
  getTitle?(): Promise<string> | string;
  /**
   * §4/§5 command execution asked from a plugin webview: the same registry
   * path as menu execution — enablement (§5.4), §4.1 singleton reuse,
   * host-authored context — scoped to the calling plugin's own declared
   * commands. The optional context merges over the command-declared context
   * (caller wins; reserved identity fields are host-owned) and feeds
   * `instance_key` `{{path}}` placeholders, so per-connection instances are
   * one `logs:{{connectionId}}` declaration away. Resolves `{ error }` for
   * expected business outcomes; only bridge or permission failures reject.
   */
  executeCommand?(pluginId: string, commandId: string, context?: Record<string, unknown>): Promise<{ error?: string } | null | void> | { error?: string } | null | void;
  openFilesystem?(pluginId: string, providerId: string, context?: PluginWorkbenchContext): Promise<void> | void;
  /** Explicit user-triggered reconnect of an owned plugin connection (full flow, interactive password prompt allowed). */
  reopenConnection?(pluginId: string, connectionId: string): Promise<void>;
  /**
   * PR-A4 generic extension point: a read-only, secret-free connection list scoped to the calling plugin's own
   * connection-providers, so plugins can implement their own connection switching inside panels/workbenches and
   * their own business (the host stays unaware of the purpose).
   *
   * With `host.connections:read` (#12603), returns all connections when requested.
   */
  listConnections?(pluginId: string, options?: { all?: boolean }): PluginConnectionSummary[];
  listAllConnections?(): PluginConnectionSummary[];
  /**
   * Estimated plan capability metadata for one connection. Requires the plugin
   * to declare `host.plans:read`. The host only reads the stored connection
   * config; it never connects or probes the server.
   */
  getPlanCapabilities?(connectionId: string): Promise<PluginPlanCapabilities>;
  /**
   * Read-only estimated plan acquisition. Requires `host.plans:read`. The host
   * generates and owns the EXPLAIN statement; the plugin cannot pass one.
   */
  explainPlan?(request: PluginPlanRequest): Promise<PluginPlanResult>;
  /** Read-only table schema metadata over an already-open Host connection. */
  getTableMetadata?(context: PluginTableContext): Promise<PluginTableMetadata>;
  /**
   * One read-only SQL statement on a connection the user granted to the
   * plugin (`host.data:read`). The backend re-checks the permission, the
   * grant, the open connection, and the read-only statement gate.
   */
  queryData?(pluginId: string, request: PluginDataQueryRequest): Promise<PluginDataQueryResult>;
  /** Whether the user already granted `pluginId` data access to `connectionId`. */
  hasDataGrant?(pluginId: string, connectionId: string): Promise<boolean>;
  /**
   * Asks the user whether `pluginId` may read `connectionId`. Resolves true to
   * allow; the bridge then persists the grant through `grantDataAccess`. A
   * host without a consent surface must omit it so the bridge denies.
   */
  confirmDataAccess?(pluginId: string, pluginName: string, connectionId: string): Promise<boolean> | boolean;
  /** Persists the grant the user just allowed. */
  grantDataAccess?(pluginId: string, connectionId: string): Promise<void>;
  closeTab?(): Promise<void> | void;
  /**
   * Floating plugin windows (the §8.3 "window" surface): a frameless,
   * always-on-top desktop widget outside the main shell. Desktop hosts only — a
   * host without it omits these so `capabilities.floating` stays false and the
   * plugin can fall back to an in-shell surface (tab or dock).
   *
   * Geometry is host-owned end to end: the plugin asks to open/close its window
   * and reports drag intent, while positions, work-area snapping, and DPI
   * conversion stay here. A drag is driven by the native cursor position rather
   * than plugin-supplied coordinates, which would be relative to a viewport that
   * is itself moving.
   */
  openFloatingWindow?(request: OpenFloatingWindowRequest): Promise<OpenFloatingWindowResult>;
  /** Closes floating windows by host label; callers derive labels from their own manifest, never from plugin input. */
  closeFloatingWindows?(labels: string[]): Promise<void>;
  /** Hands the calling floating window's movement to the OS drag loop. */
  beginFloatingDrag?(): Promise<void>;
  /** Ends a drag, snapping the window onto the work-area edges it landed near. Resolves the final physical rect. */
  endFloatingDrag?(snap: boolean): Promise<FloatingRect | null>;
  /** Resizes the calling floating window (logical pixels). */
  setFloatingSize?(width: number, height: number): Promise<void>;
  /** Persist plugin bytes through the host's native save dialog. Resolves null when the user cancels. */
  saveFile?(pluginId: string, request: PluginSaveFileRequest, data: Uint8Array): Promise<PluginSaveFileResult | null>;
  downloadFile?(pluginId: string, request: PluginDownloadRequest, onProgress: (progress: unknown) => void): Promise<PluginSaveFileResult | null>;
  cancelDownload?(pluginId: string, downloadId: string): Promise<void>;
  /** Write text to the system clipboard on behalf of the sandboxed plugin iframe. */
  copyText?(pluginId: string, text: string): Promise<void>;
  /**
   * Read the system clipboard on behalf of the sandboxed plugin iframe.
   * Requires the plugin to declare `host.clipboard:read`: unlike writes, a
   * read hands arbitrary user data (passwords, tokens) to plugin code with no
   * further user interaction, so it is permission-gated.
   */
  clipboardRead?(pluginId: string): Promise<string>;
  /** Read and PNG-encode the current clipboard image. Shares the clipboard-read permission and consent gate. */
  clipboardReadImage?(pluginId: string): Promise<PluginClipboardImage>;
  /**
   * Session consent prompt for the first clipboard read of a bridge lifetime.
   * Resolves true to allow (and remember for the workbench session), false to
   * deny (the read request rejects). Optional on hosts without a dialog
   * surface; a host that cannot ask must not silently allow.
   */
  confirmClipboardRead?(pluginId: string, pluginName: string): Promise<boolean> | boolean;
  /** Register a short-lived, plugin-scoped custom-protocol media source. */
  openMedia?(pluginId: string, method: string, params: Record<string, unknown>): Promise<string>;
  /** Revoke a media source token previously returned by openMedia. */
  closeMedia?(pluginId: string, token: string): Promise<void>;
  /** Native open dialog; resolves opened read handles (null selection → empty list). */
  pickFiles?(pluginId: string, options: PluginPickFilesOptions): Promise<PluginFileHandleMeta[]>;
  /** Stream a chunk from an opened read handle. */
  readFileChunk?(pluginId: string, handleId: string, offset: number, length?: number): Promise<PluginFileReadChunk>;
  /** Native save dialog + opened write handle; resolves null when the user cancels. */
  beginFileSave?(pluginId: string, request: { name?: string; contentType?: string; size?: number }): Promise<{ handleId: string; chunkBytes: number } | null>;
  /** Stream a chunk into an opened write handle. */
  writeFileChunk?(pluginId: string, handleId: string, offset: number, bytes: Uint8Array): Promise<PluginFileWriteResult>;
  /** Flush and close an opened write handle. */
  finishFileSave?(pluginId: string, handleId: string): Promise<void>;
  /** Close any file handle, discarding unsaved state. */
  closeFileHandle?(pluginId: string, handleId: string): Promise<void>;
  /** Whether this host receives OS file drops on the plugin's behalf (desktop only). */
  receiveOsDrops?: boolean;
  /** Persistent per-plugin key-value storage for sandboxed UIs; resolves null when the key is unset. */
  storageGet?(pluginId: string, key: string): Promise<unknown>;
  storageSet?(pluginId: string, key: string, value: unknown): Promise<void>;
  storageDelete?(pluginId: string, key: string): Promise<void>;
}

export interface PluginAiRecommendationHostUpdate {
  pluginId: string;
  pluginName: string;
  contributionId: string;
  workbenchId: string;
  context: PluginAiRecommendationContext;
  items: readonly PluginAiRecommendation[];
}

interface PluginRequestMessage {
  source: typeof PLUGIN_MESSAGE_SOURCE;
  version: typeof BRIDGE_VERSION;
  type: "request";
  id: string;
  method: string;
  params?: unknown;
  /** Optional zero-copy binary payload transferred with the request. */
  data?: ArrayBuffer;
}

export class PluginHostBridge {
  private downloads = new Set<string>();
  private mediaTokens = new Set<string>();
  private context: PluginWorkbenchContext;
  private locale: string;
  private theme?: PluginBridgeTheme;
  /** Consent + audit + rate state for clipboard reads; lives for the bridge lifetime. */
  private clipboardReadGate = createClipboardReadGate();
  /**
   * Data-access answers for this bridge lifetime, per connection. A denial is
   * remembered so a plugin cannot re-prompt in a loop; an iframe reload builds
   * a new bridge and may ask again. Grants live in the backend; this only
   * spares a lookup per query.
   */
  private dataAccess = new Map<string, "granted" | "denied">();
  /** One consent prompt per connection at a time; concurrent queries share it. */
  private pendingDataAccess = new Map<string, Promise<void>>();
  private inFlightDataQueries = 0;
  private runtimeAiRecommendations: PluginAiRecommendationUpdate | null | undefined;
  /** Active streamed AI generations of this bridge, by plugin-supplied requestId. */
  private activeAiStreams = new Set<string>();

  /** Bounded audit trail of this session's clipboard read attempts (oldest first). */
  get clipboardAudit(): readonly PluginClipboardAuditEntry[] {
    return this.clipboardReadGate.audit;
  }

  /** Invoked once before each iframe load generation sends its init message. */
  onReinit?: () => Promise<void> | void;

  constructor(
    private readonly plugin: InstalledPlugin,
    private readonly contribution: PluginUiContribution,
    context: PluginWorkbenchContext,
    private readonly targetWindow: () => Window | null,
    private readonly api: PluginHostBridgeApi,
    locale = "en",
    theme?: PluginBridgeTheme,
  ) {
    this.context = snapshotPluginWorkbenchContext(context);
    this.locale = locale;
    this.theme = theme ? clonePluginData(theme) : undefined;
    this.publishAiRecommendations();
  }

  handleWindowMessage(event: MessageEvent): boolean {
    const target = this.targetWindow();
    if (!target || event.source !== target || !isRecord(event.data)) return false;
    if (event.data.source !== PLUGIN_MESSAGE_SOURCE || event.data.version !== BRIDGE_VERSION) return false;
    if (event.data.type === "ready") {
      // Feature flags the SDK advertises at boot; unknown flags are ignored so
      // host/plugin can evolve independently.
      this.advertisedFeatures = new Set(Array.isArray(event.data.features) ? event.data.features.filter((feature): feature is string => typeof feature === "string") : []);
      void this.handleReady();
      return true;
    }
    if (event.data.type === "workbench/close-ack") {
      // Two-phase close handshake (§8.3): the plugin released its workbench scope.
      this.pendingCloseAck?.();
      this.pendingCloseAck = undefined;
      return true;
    }
    if (event.data.type === "shortcut" && event.data.shortcut === "closeTab") {
      void this.api.closeTab?.();
      return true;
    }
    if (event.data.type !== "request" || !validRequestMessage(event.data)) return false;
    void this.handleRequest(event.data, target);
    return true;
  }

  private handleReady(): void {
    this.requestInit("ready");
  }

  sendInit(): void {
    this.requestInit("load");
  }

  private requestInit(signal: "load" | "ready"): void {
    if ((this.initSignals.load && this.initSignals.ready) || (signal === "load" && this.initSignals.load)) {
      for (const downloadId of this.downloads) void this.api.cancelDownload?.(this.plugin.manifest.id, downloadId).catch(() => undefined);
      this.downloads.clear();
      for (const token of this.mediaTokens) void this.api.closeMedia?.(this.plugin.manifest.id, token).catch(() => undefined);
      this.mediaTokens.clear();
      this.initGeneration += 1;
      this.initSignals = { load: false, ready: false };
      this.initStarted = false;
    }
    if (this.initSignals[signal]) return;
    this.initSignals[signal] = true;
    if (this.initStarted) return;
    this.initStarted = true;
    const generation = this.initGeneration;
    const reinit = this.onReinit;
    if (!reinit) {
      if (!this.disposed && generation === this.initGeneration) this.postInit();
      return;
    }
    void (async () => {
      try {
        await reinit();
      } catch (error) {
        console.warn("[DBX][plugin-bridge:reinit]", error);
      }
      // A newer load generation supersedes this one; never post a stale init.
      if (!this.disposed && generation === this.initGeneration) this.postInit();
    })();
  }

  /** Stop future posts (queued inits after an async reinit) for a torn-down bridge. */
  dispose(): void {
    this.disposed = true;
    for (const downloadId of this.downloads) void this.api.cancelDownload?.(this.plugin.manifest.id, downloadId).catch(() => undefined);
    this.downloads.clear();
    // Best-effort: a torn-down workbench must not keep a provider stream
    // running with nobody to receive its chunks.
    for (const requestId of this.activeAiStreams) void this.api.cancelAiGeneration?.(requestId).catch(() => undefined);
    this.activeAiStreams.clear();
    for (const token of this.mediaTokens) void this.api.closeMedia?.(this.plugin.manifest.id, token).catch(() => undefined);
    this.mediaTokens.clear();
    this.publishAiRecommendations({ context: {}, items: [] });
  }

  private disposed = false;
  private initGeneration = 0;
  private initSignals = { load: false, ready: false };
  private initStarted = false;
  private advertisedFeatures = new Set<string>();
  private pendingCloseAck?: () => void;

  /**
   * §8.3/§7.4 two-phase workbench close: give the plugin a chance to release
   * its workbench scope (PTY sessions, subscriptions, temporary state) before
   * the webview is torn down. Resolves true when the plugin acked; false when
   * the handshake is unsupported (legacy SDK advertises no "workbench.close"
   * feature) or the ack did not arrive inside the deadline. Either way the
   * caller proceeds with teardown.
   */
  requestWorkbenchClose(timeoutMs = 400): Promise<boolean> {
    if (this.disposed || !this.targetWindow()) return Promise.resolve(false);
    const supported = this.advertisedFeatures.has("workbench.close");
    if (!supported) {
      // Legacy SDK: the message is inert, so do not stall the close on it.
      this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "workbench/close", workbenchId: "" });
      return Promise.resolve(false);
    }
    const workbenchId = typeof this.context.workbenchId === "string" ? this.context.workbenchId : "";
    return new Promise((resolve) => {
      let settled = false;
      const settle = (acked: boolean) => {
        if (settled) return;
        settled = true;
        this.pendingCloseAck = undefined;
        resolve(acked);
      };
      this.pendingCloseAck = () => settle(true);
      this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "workbench/close", workbenchId });
      setTimeout(() => settle(false), timeoutMs);
    });
  }

  private postInit(): void {
    this.post({
      source: HOST_MESSAGE_SOURCE,
      version: BRIDGE_VERSION,
      type: "init",
      pluginId: this.plugin.manifest.id,
      contributionId: this.contribution.id,
      locale: this.locale,
      theme: this.theme ? clonePluginData(this.theme) : undefined,
      permissions: [...(this.plugin.manifest.permissions || [])],
      // Additive capability advertisement: an older host omits `planApi`, and a
      // plugin must treat the absence as "unsupported" rather than probing.
      capabilities: {
        downloadFile: !!this.api.downloadFile,
        planApi: !!this.api.getPlanCapabilities && !!this.api.explainPlan,
        [PLUGIN_SCHEMA_METADATA_CAPABILITY]: !!this.api.getTableMetadata,
        [PLUGIN_DATA_CAPABILITY]: !!this.api.queryData && !!this.api.hasDataGrant && !!this.api.confirmDataAccess && !!this.api.grantDataAccess,
        storage: !!this.api.storageGet && !!this.api.storageSet && !!this.api.storageDelete,
        ai: !!this.api.openAiConversation,
        aiModelDiscovery: !!this.api.listAiProviders && !!this.api.discoverAiModels,
        aiCompletion: !!this.api.listAiModels && !!this.api.generateAiText,
        // Streaming generation goes together with per-request cancellation;
        // advertising both or neither keeps the capability honest.
        aiCompletionStream: !!this.api.generateAiTextStream && !!this.api.cancelAiGeneration,
        aiRecommendations: !!this.api.openAiConversation && !!this.api.setAiRecommendations,
        // Additive with the same "absence means unsupported" contract: an older
        // host omits these, and a web host has neither.
        clipboardWrite: !!this.api.copyText,
        clipboardRead: !!this.api.clipboardRead,
        clipboardImageRead: !!this.api.clipboardReadImage,
        mediaUrl: !!this.api.openMedia && !!this.api.closeMedia,
        // Floating desktop widget windows: advertised only when the host can both
        // open a window and drive its geometry, so a plugin sees one honest flag.
        floating: !!this.api.openFloatingWindow && !!this.api.beginFloatingDrag && !!this.api.endFloatingDrag,
        workbenchTitle: !!this.api.setTitle,
        // The namespace exists on both hosts, but what it can DO differs:
        // portable plugins gate on these flags instead of probing calls.
        fileTransfer: {
          pick: !!this.api.pickFiles,
          beginSave: !!this.api.beginFileSave && !!this.api.writeFileChunk && !!this.api.finishFileSave,
          read: !!this.api.readFileChunk,
          // OS drops (and their folder expansion) are desktop-only.
          drop: !!this.api.receiveOsDrops,
          folderExpansion: !!this.api.receiveOsDrops,
        },
        [PLUGIN_CONNECTIONS_CAPABILITY]: !!this.api.listConnections || !!this.api.listAllConnections,
      },
      context: snapshotPluginWorkbenchContext(this.context),
    });
  }

  /**
   * Push a new workbench context into the already-loaded plugin UI instead of
   * rebuilding the iframe. Identity changes (plugin/contribution) still require
   * a full reload; context-only changes must not lose plugin state.
   */
  updateContext(context: PluginWorkbenchContext): void {
    this.context = snapshotPluginWorkbenchContext(context);
    this.runtimeAiRecommendations = undefined;
    this.publishAiRecommendations();
    this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "context", context: snapshotPluginWorkbenchContext(this.context) });
  }

  private publishAiRecommendations(override?: PluginAiRecommendationUpdate): void {
    if (!this.hasPermission("host.ai") || !this.api.openAiConversation || !this.api.setAiRecommendations) return;
    const workbenchId = typeof this.context.workbenchId === "string" ? this.context.workbenchId : "";
    const contribution = this.contribution.type === "workbench" ? this.contribution : undefined;
    const defaults = contribution?.ai?.recommendations;
    const runtime = override ?? this.runtimeAiRecommendations;
    // Runtime updates usually contain only the resource-specific fields used by
    // placeholders. Keep host-owned routing fields authoritative so clicking a
    // recommendation remains bound to this workbench's connection even when the
    // plugin does not repeat connectionId in every update.
    const runtimeContext = runtime
      ? snapshotPluginWorkbenchContext({
          ...runtime.context,
          ...(this.context.connectionId === undefined ? {} : { connectionId: this.context.connectionId }),
          ...(this.context.database === undefined ? {} : { database: this.context.database }),
          ...(this.context.schema === undefined ? {} : { schema: this.context.schema }),
          ...(this.context.workbenchId === undefined ? {} : { workbenchId: this.context.workbenchId }),
        })
      : this.context;
    const effectiveRuntime = runtime === null ? { context: {}, items: [] } : runtime ? { ...runtime, context: runtimeContext } : undefined;
    const items = resolvePluginAiRecommendationUpdate(defaults, effectiveRuntime, this.context);
    this.api.setAiRecommendations({
      pluginId: this.plugin.manifest.id,
      pluginName: this.plugin.manifest.name,
      contributionId: this.contribution.id,
      workbenchId,
      context: runtime ? runtimeContext : this.context,
      items,
    });
  }

  /** Notify the plugin UI about a locale change without a reload. */
  updateLocale(locale: string): void {
    this.locale = locale;
    this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "env", locale });
  }

  /** Push resolved theme tokens so the plugin UI can follow DBX light/dark and palette changes. */
  updateTheme(theme: PluginBridgeTheme): void {
    this.theme = clonePluginData(theme);
    this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "env", locale: this.locale, theme: this.theme });
  }

  forwardEvent(event: PluginEvent): void {
    if (event.pluginId !== this.plugin.manifest.id || !this.hasPermission("host.events")) return;
    this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "event", method: event.method, params: event.params });
  }

  forwardBinary(event: PluginBinaryEvent): void {
    if (event.pluginId !== this.plugin.manifest.id || !this.hasPermission("host.binary")) return;
    const target = this.targetWindow();
    if (!target) return;
    const buffer = base64ToBytes(event.dataBase64);
    target.postMessage({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "binary", channel: event.channel, data: buffer }, "*", [buffer]);
  }

  /** Tell the plugin whether an OS-level file drag is currently over its workbench. */
  forwardDragState(active: boolean, position?: PluginDragPosition): void {
    this.post({
      source: HOST_MESSAGE_SOURCE,
      version: BRIDGE_VERSION,
      type: "dragstate",
      active,
      position: position ? { x: position.x, y: position.y } : undefined,
    });
  }

  /** Hand the plugin already-opened handles for files dropped onto its workbench. */
  forwardFileDrop(files: PluginFileHandleMeta[], drop?: { dropId?: string; truncated?: boolean; position?: PluginDragPosition }): void {
    this.post({
      source: HOST_MESSAGE_SOURCE,
      version: BRIDGE_VERSION,
      type: "filedrop",
      files,
      dropId: drop?.dropId,
      truncated: drop?.truncated === true,
      position: drop?.position ? { x: drop.position.x, y: drop.position.y } : undefined,
    });
  }

  private async handleRequest(request: PluginRequestMessage, target: Window): Promise<void> {
    try {
      enforcePayloadLimit(request.params);
      const result = await this.dispatch(request.method, request.params, request.data);
      this.respond(target, request.id, { result: result ?? null });
    } catch (error) {
      this.respond(target, request.id, { error: error instanceof Error ? error.message : String(error) });
    }
  }

  private async dispatch(method: string, params: unknown, binary?: ArrayBuffer): Promise<unknown> {
    if (method === "host.downloadFile") {
      if (!this.api.downloadFile) throw new Error("Streaming file downloads require the desktop host");
      const input = requireRecord(params, "download params");
      const downloadId = requireProtocolName(input.downloadId, "download ID");
      if (this.downloads.size >= 2 || this.downloads.has(downloadId)) throw new Error("Too many active downloads or duplicate download ID");
      const request = { downloadId, fileName: optionalTrimmedString(input.fileName), params: requireRecord(input.params, "download source") };
      this.downloads.add(downloadId);
      try {
        return await this.api.downloadFile(this.plugin.manifest.id, request, (progress) => {
          this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "event", method: "host.download.progress", params: progress });
        });
      } finally {
        this.downloads.delete(downloadId);
      }
    }
    if (method === "host.cancelDownload") {
      const input = requireRecord(params, "cancel download params");
      const downloadId = requireProtocolName(input.downloadId, "download ID");
      if (this.downloads.has(downloadId)) await this.api.cancelDownload?.(this.plugin.manifest.id, downloadId);
      return null;
    }
    if (method === "host.getContext") return snapshotPluginWorkbenchContext(this.context);
    if (method === "host.ai.listProviders") {
      this.requirePermission("host.ai");
      if (!this.api.listAiProviders) throw new Error("AI provider selection is unavailable");
      return (await this.api.listAiProviders()).map((p) => ({ configId: p.configId, name: p.name }));
    }
    if (method === "host.ai.discoverModels") {
      this.requirePermission("host.ai");
      if (!this.api.discoverAiModels) throw new Error("AI model discovery is unavailable");
      const input = requireRecord(params, "AI model discovery");
      if (typeof input.configId !== "string" || !input.configId.trim() || input.configId.length > 256) throw new Error("Invalid AI configId");
      return (await this.api.discoverAiModels(input.configId)).map((m) => ({ configId: m.configId, name: m.name, model: m.model, isDefault: !!m.isDefault }));
    }
    if (method === "host.ai.listModels") {
      this.requirePermission("host.ai");
      if (!this.api.listAiModels) throw new Error("DBX AI model selection is unavailable");
      // Whitelist response fields even if an adapter accidentally returns config objects.
      return (await this.api.listAiModels()).map((m) => ({ configId: m.configId, name: m.name, model: m.model, isDefault: !!m.isDefault }));
    }
    if (method === "host.ai.generateText") {
      this.requirePermission("host.ai");
      if (!this.api.generateAiText) throw new Error("DBX AI text generation is unavailable");
      const input = requireRecord(params, "AI generation request");
      for (const key of ["configId", "model", "prompt"] as const) {
        if (typeof input[key] !== "string" || !input[key].trim() || input[key].length > (key === "prompt" ? 100000 : 256)) throw new Error("Invalid AI " + key);
      }
      // Task presets are a closed host-owned enum: a plugin picks a template,
      // it never writes system text. Unknown values fail loudly.
      const task = input.task === undefined || input.task === null ? undefined : requirePluginAiTask(input.task);
      return this.api.generateAiText(this.plugin.manifest.name, { configId: input.configId as string, model: input.model as string, prompt: input.prompt as string, ...(task === undefined ? {} : { task }) });
    }
    if (method === "host.ai.generateTextStream") {
      this.requirePermission("host.ai");
      // Same conjunction the aiCompletionStream capability advertises: a host
      // that cannot cancel does not stream.
      if (!this.api.generateAiTextStream || !this.api.cancelAiGeneration) throw new Error("DBX AI text generation streaming is unavailable");
      const input = requireRecord(params, "AI generation request");
      for (const key of ["configId", "model", "prompt"] as const) {
        if (typeof input[key] !== "string" || !input[key].trim() || input[key].length > (key === "prompt" ? 100000 : 256)) throw new Error("Invalid AI " + key);
      }
      const requestId = requireProtocolName(input.requestId, "AI requestId");
      if (this.activeAiStreams.has(requestId)) throw new Error("Duplicate AI requestId");
      const task = input.task === undefined || input.task === null ? undefined : requirePluginAiTask(input.task);
      this.activeAiStreams.add(requestId);
      try {
        // Same event channel as host.download.progress: incremental chunks are
        // delivered as host.ai.generationChunk events that plugins filter by
        // requestId; the call itself resolves with the full text.
        return await this.api.generateAiTextStream(this.plugin.manifest.name, { configId: input.configId as string, model: input.model as string, prompt: input.prompt as string, requestId, ...(task === undefined ? {} : { task }) }, (chunk) => {
          if (!this.activeAiStreams.has(requestId)) return;
          this.post({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "event", method: "host.ai.generationChunk", params: { requestId, delta: chunk.delta, done: chunk.done === true } });
        });
      } finally {
        this.activeAiStreams.delete(requestId);
      }
    }
    if (method === "host.ai.cancelGeneration") {
      const input = requireRecord(params, "AI cancel request");
      const requestId = requireProtocolName(input.requestId, "AI requestId");
      // Scoped like host.cancelDownload: a workbench may only cancel the
      // streams it started. Unknown or finished ids answer { cancelled: false }.
      if (!this.activeAiStreams.has(requestId) || !this.api.cancelAiGeneration) return { cancelled: false };
      const cancelled = (await this.api.cancelAiGeneration(requestId)) === true;
      // A confirmed cancel also stops chunk forwarding immediately; the
      // stream's own settle path becomes a no-op delete.
      if (cancelled) this.activeAiStreams.delete(requestId);
      return { cancelled };
    }
    if (method === "host.ai.openConversation") {
      this.requirePermission("host.ai");
      if (!this.api.openAiConversation) throw new Error("DBX AI conversation panel is unavailable");
      const request = createPluginAiConversation(this.plugin.manifest, params);
      await this.api.openAiConversation(request);
      return null;
    }
    if (method === "host.ai.setRecommendations") {
      this.requirePermission("host.ai");
      if (!this.api.openAiConversation || !this.api.setAiRecommendations) throw new Error("DBX AI recommendations are unavailable");
      const update = requirePluginAiRecommendationUpdate(params);
      this.runtimeAiRecommendations = update;
      this.publishAiRecommendations();
      return null;
    }
    if (method === "host.ai.clearRecommendations") {
      this.requirePermission("host.ai");
      if (!this.api.openAiConversation || !this.api.setAiRecommendations) throw new Error("DBX AI recommendations are unavailable");
      this.runtimeAiRecommendations = { context: {}, items: [] };
      this.publishAiRecommendations();
      return null;
    }
    if (method === "backend.invoke") {
      const input = requireRecord(params, "backend.invoke params");
      const backendMethod = requireProtocolName(input.method, "backend method");
      const timeoutMs = input.timeoutMs === undefined ? undefined : requireTimeout(input.timeoutMs);
      return this.api.invoke(this.plugin.manifest.id, backendMethod, input.params ?? null, timeoutMs);
    }
    if (method === "backend.notify") {
      const input = requireRecord(params, "backend.notify params");
      await this.api.notify(this.plugin.manifest.id, requireProtocolName(input.method, "backend method"), input.params ?? null);
      return null;
    }
    if (method === "backend.sendBinary") {
      this.requirePermission("host.binary");
      const input = requireRecord(params, "backend.sendBinary params");
      const channel = requireProtocolName(input.channel, "binary channel");
      if (binary instanceof ArrayBuffer) {
        if (binary.byteLength > MAX_BRIDGE_BINARY_BYTES) throw new Error("Plugin binary payload exceeds 8 MiB; chunk the transfer");
        await this.api.sendBinary(this.plugin.manifest.id, channel, bytesToBase64(new Uint8Array(binary)));
        return null;
      }
      await this.api.sendBinary(this.plugin.manifest.id, channel, requireBase64(input.dataBase64));
      return null;
    }
    if (method === "host.mediaOpen") {
      if (!this.api.openMedia || !this.api.closeMedia) throw new Error("Host media URLs are unavailable");
      const input = requireRecord(params, "media params");
      const backendMethod = requireProtocolName(input.method, "media backend method");
      const backendParams = requireRecord(input.params, "media backend params");
      const token = await this.api.openMedia(this.plugin.manifest.id, backendMethod, backendParams);
      this.mediaTokens.add(token);
      return { token };
    }
    if (method === "host.mediaClose") {
      const input = requireRecord(params, "media close params");
      const token = requireProtocolName(input.token, "media token");
      if (this.mediaTokens.delete(token)) await this.api.closeMedia?.(this.plugin.manifest.id, token);
      return null;
    }
    if (method === "ui.readAsset") {
      const input = requireRecord(params, "ui.readAsset params");
      return this.api.readAsset(this.plugin.manifest.id, requireSafeAssetPath(input.path));
    }
    if (method === "host.openWorkbench") {
      this.requirePermission("host.workbench");
      if (!this.api.openWorkbench) throw new Error("Host workbench navigation is unavailable");
      const input = requireRecord(params, "host.openWorkbench params");
      // `target: "tab"` lets a dock-hosted webview ask for a main-workbench
      // tab instead of another dock entry (e.g. the SSH dock's "open session
      // in tab" button). Surfaces that ignore it keep the old behavior, so
      // older handlers stay compatible.
      await this.api.openWorkbench(this.plugin.manifest.id, requireProtocolName(input.contributionId, "workbench contribution"), isRecord(input.context) ? input.context : undefined, { forceNew: input.forceNew === true, target: input.target === "tab" ? "tab" : undefined });
      return null;
    }
    if (method === "host.setTitle") {
      this.requirePermission("host.workbench");
      if (!this.api.setTitle) throw new Error("Host tab title update is unavailable");
      const input = requireRecord(params, "setTitle params");
      const rawTitle = input.title;
      const title = typeof rawTitle === "string" ? rawTitle.trim().slice(0, 256) || null : null;
      await this.api.setTitle(title);
      return null;
    }
    if (method === "host.getTitle") {
      this.requirePermission("host.workbench");
      if (!this.api.getTitle) throw new Error("Host tab title read is unavailable");
      return (await this.api.getTitle()) ?? "";
    }
    if (method === "host.executeCommand") {
      this.requirePermission("host.workbench");
      if (!this.api.executeCommand) throw new Error("Host command execution is unavailable");
      const input = requireRecord(params, "host.executeCommand params");
      return (await this.api.executeCommand(this.plugin.manifest.id, requireProtocolName(input.commandId, "command id"), isRecord(input.context) ? input.context : undefined)) ?? {};
    }
    if (method === "host.reopenConnection") {
      if (!this.api.reopenConnection) throw new Error("Connection reopen is unavailable");
      const input = requireRecord(params, "host.reopenConnection params");
      await this.api.reopenConnection(this.plugin.manifest.id, requireProtocolName(input.connectionId, "connectionId"));
      return { ok: true };
    }
    if (method === "host.getConnections") {
      this.requirePermission(PLUGIN_CONNECTIONS_READ_PERMISSION);
      if (!this.api.listConnections && !this.api.listAllConnections) throw new Error("Connection enumeration is unavailable on this host");
      if (this.api.listAllConnections) return this.api.listAllConnections();
      return this.api.listConnections!(this.plugin.manifest.id, { all: true });
    }
    if (method === "host.listConnections") {
      const hasConnectionsRead = this.hasPermission(PLUGIN_CONNECTIONS_READ_PERMISSION);
      const forceScoped = isRecord(params) && params.scoped === true;
      if (!hasConnectionsRead) {
        this.requirePermission("host.workbench");
      }
      if (!this.api.listConnections && !this.api.listAllConnections) throw new Error("Connection enumeration is unavailable on this host");
      if (hasConnectionsRead && !forceScoped) {
        if (this.api.listAllConnections) return this.api.listAllConnections();
        return this.api.listConnections!(this.plugin.manifest.id, { all: true });
      }
      return this.api.listConnections ? this.api.listConnections(this.plugin.manifest.id) : [];
    }
    if (method === "host.openFilesystem") {
      this.requirePermission("host.filesystem");
      if (!this.api.openFilesystem) throw new Error("Host filesystem navigation is unavailable");
      const input = requireRecord(params, "host.openFilesystem params");
      await this.api.openFilesystem(this.plugin.manifest.id, requireProtocolName(input.providerId, "filesystem provider"), isRecord(input.context) ? input.context : undefined);
      return null;
    }
    if (method === "host.getPlanCapabilities") {
      this.requirePermission(PLUGIN_PLAN_PERMISSION);
      if (!this.api.getPlanCapabilities) throw new Error("Host plan API is unavailable");
      const input = requireRecord(params, "host.getPlanCapabilities params");
      return this.api.getPlanCapabilities(requirePluginPlanIdentifier(input.connectionId, "connectionId"));
    }
    if (method === "host.explainPlan") {
      this.requirePermission(PLUGIN_PLAN_PERMISSION);
      if (!this.api.explainPlan) throw new Error("Host plan API is unavailable");
      return this.api.explainPlan(requirePluginPlanRequest(requireRecord(params, "host.explainPlan params")));
    }
    if (method === "host.getTableMetadata") {
      this.requirePermission(PLUGIN_SCHEMA_METADATA_PERMISSION);
      if (!this.api.getTableMetadata) throw new Error("Host schema metadata API is unavailable");
      return this.api.getTableMetadata(requirePluginTableContext(requireRecord(params, "host.getTableMetadata params")));
    }
    if (method === "host.queryData") {
      this.requirePermission(PLUGIN_DATA_READ_PERMISSION);
      if (!this.api.queryData) throw new Error("Host data API is unavailable");
      const request = requirePluginDataQueryRequest(requireRecord(params, "host.queryData params"));
      await this.ensureDataAccess(request.connectionId);
      if (this.inFlightDataQueries >= MAX_CONCURRENT_PLUGIN_DATA_QUERIES) {
        throw new Error(`At most ${MAX_CONCURRENT_PLUGIN_DATA_QUERIES} data queries may run at once; wait for one to finish`);
      }
      this.inFlightDataQueries += 1;
      try {
        return await this.api.queryData(this.plugin.manifest.id, request);
      } catch (error) {
        // The grant was revoked while this workbench stayed open: forget the
        // cached answer so the next query asks the user again.
        if ((error instanceof Error ? error.message : String(error)).includes(PLUGIN_DATA_ACCESS_NOT_GRANTED)) this.dataAccess.delete(request.connectionId);
        throw error;
      } finally {
        this.inFlightDataQueries -= 1;
      }
    }
    if (method === "host.saveFile") {
      const input = isRecord(params) ? params : {};
      // The sandboxed iframe cannot trigger downloads (WKWebView cancels blob
      // navigations without a host download handler), so plugins hand the bytes
      // to the host, which runs the native save dialog and the disk write.
      let bytes: Uint8Array;
      if (binary instanceof ArrayBuffer) bytes = new Uint8Array(binary);
      else if (typeof input.dataBase64 === "string") bytes = new Uint8Array(base64ToBytes(requireBase64(input.dataBase64)));
      else throw new Error("host.saveFile requires transferred binary data or dataBase64");
      if (bytes.byteLength > MAX_BRIDGE_SAVE_BYTES) throw new Error(`Plugin save payload exceeds ${MAX_BRIDGE_SAVE_BYTES} bytes`);
      if (!this.api.saveFile) throw new Error("Host file saving is unavailable");
      return this.api.saveFile(this.plugin.manifest.id, { fileName: optionalTrimmedString(input.fileName), contentType: optionalTrimmedString(input.contentType) }, bytes);
    }
    if (method === "host.copy") {
      const input = isRecord(params) ? params : {};
      // The sandboxed workbench iframe has an opaque origin and no clipboard
      // permission, so every scripted copy path is denied there; the host
      // writes the system clipboard instead.
      if (typeof input.text !== "string" || !input.text) throw new Error("host.copy requires text");
      if (input.text.length > MAX_BRIDGE_PAYLOAD_BYTES) throw new Error(`Plugin copy payload exceeds ${MAX_BRIDGE_PAYLOAD_BYTES} characters`);
      if (!this.api.copyText) throw new Error("Host clipboard is unavailable");
      await this.api.copyText(this.plugin.manifest.id, input.text);
      return { success: true };
    }
    if (method === "host.clipboardRead") {
      // Reads are the sensitive half of the clipboard surface: the payload is
      // user data heading into plugin code, so the manifest must declare
      // `host.clipboard:read` (writes stay on ungated host.copy).
      this.requirePermission("host.clipboard:read");
      if (!this.api.clipboardRead) throw new Error("Host clipboard read is unavailable");
      const now = await this.requireClipboardRead();
      const text = await this.api.clipboardRead(this.plugin.manifest.id);
      if (typeof text !== "string") throw new Error("Host clipboard read returned a non-string value");
      const clamped = text.length > MAX_BRIDGE_PAYLOAD_BYTES ? text.slice(0, MAX_BRIDGE_PAYLOAD_BYTES) : text;
      recordClipboardRead(this.clipboardReadGate, now, "granted", clamped.length);
      return { text: clamped };
    }
    if (method === "host.clipboardReadImage") {
      this.requirePermission("host.clipboard:read");
      if (!this.api.clipboardReadImage) throw new Error("Host clipboard image read is unavailable");
      const now = await this.requireClipboardRead();
      const image = await this.api.clipboardReadImage(this.plugin.manifest.id);
      if (image.contentType !== "image/png" || !Number.isSafeInteger(image.width) || image.width <= 0 || !Number.isSafeInteger(image.height) || image.height <= 0) {
        throw new Error("Host clipboard image returned invalid metadata");
      }
      const dataBase64 = requireBase64(image.dataBase64);
      if (dataBase64.length > MAX_CLIPBOARD_IMAGE_BASE64_BYTES) throw new Error("Clipboard image exceeds the 18 MiB upload limit");
      recordClipboardRead(this.clipboardReadGate, now, "granted", Math.floor(dataBase64.length * 0.75));
      return { ...image, dataBase64 };
    }
    if (method === "host.pickFiles") {
      // Same trust level as host.saveFile: the bytes only flow after the user
      // picked the files in the native dialog, so no manifest permission gate.
      const input = isRecord(params) ? params : {};
      if (!this.api.pickFiles) throw new Error("Host file picking is unavailable");
      const files = await this.api.pickFiles(this.plugin.manifest.id, { multiple: input.multiple === true });
      return { files };
    }
    if (method === "host.readFileChunk") {
      const input = requireRecord(params, "host.readFileChunk params");
      if (!this.api.readFileChunk) throw new Error("Host file reading is unavailable");
      return this.api.readFileChunk(this.plugin.manifest.id, requireHandleId(input.handleId), requireOffset(input.offset), input.length === undefined ? undefined : requireChunkLength(input.length));
    }
    if (method === "host.beginFileSave") {
      const input = isRecord(params) ? params : {};
      if (!this.api.beginFileSave) throw new Error("Host file saving is unavailable");
      const target = await this.api.beginFileSave(this.plugin.manifest.id, {
        name: optionalTrimmedString(input.name),
        contentType: optionalTrimmedString(input.contentType),
        size: input.size === undefined || typeof input.size !== "number" || !Number.isFinite(input.size) ? undefined : Math.max(0, Math.floor(input.size)),
      });
      // Cancelled saves resolve null, exactly as the documented contract and
      // every plugin's env.d.ts types it.
      return target;
    }
    if (method === "host.writeFileChunk") {
      const input = requireRecord(params, "host.writeFileChunk params");
      if (!this.api.writeFileChunk) throw new Error("Host file writing is unavailable");
      const bytes = binary instanceof ArrayBuffer ? new Uint8Array(binary) : new Uint8Array(base64ToBytes(requireBase64(input.dataBase64)));
      if (bytes.byteLength > MAX_BRIDGE_BINARY_BYTES) throw new Error("Plugin write chunk exceeds 8 MiB");
      return this.api.writeFileChunk(this.plugin.manifest.id, requireHandleId(input.handleId), requireOffset(input.offset), bytes);
    }
    if (method === "host.finishFileSave") {
      const input = requireRecord(params, "host.finishFileSave params");
      if (!this.api.finishFileSave) throw new Error("Host file saving is unavailable");
      await this.api.finishFileSave(this.plugin.manifest.id, requireHandleId(input.handleId));
      return null;
    }
    if (method === "host.closeFileHandle") {
      const input = requireRecord(params, "host.closeFileHandle params");
      if (!this.api.closeFileHandle) throw new Error("Host file handling is unavailable");
      await this.api.closeFileHandle(this.plugin.manifest.id, requireHandleId(input.handleId));
      return null;
    }
    if (method === "host.storageGet") {
      this.requirePermission("host.storage");
      if (!this.api.storageGet) throw new Error("Host storage is unavailable");
      const input = requireRecord(params, "host.storageGet params");
      return this.api.storageGet(this.plugin.manifest.id, requireStorageKey(input.key));
    }
    if (method === "host.storageSet") {
      this.requirePermission("host.storage");
      if (!this.api.storageSet) throw new Error("Host storage is unavailable");
      const input = requireRecord(params, "host.storageSet params");
      const key = requireStorageKey(input.key);
      // Sized before the structured clone reaches the host implementation, so
      // the native host and the web fallback enforce the same bound.
      const bytes = new TextEncoder().encode(JSON.stringify(input.value ?? null)).byteLength;
      if (bytes > MAX_PLUGIN_STORAGE_VALUE_BYTES) {
        throw new Error(`host.storage value exceeds ${MAX_PLUGIN_STORAGE_VALUE_BYTES} bytes`);
      }
      await this.api.storageSet(this.plugin.manifest.id, key, input.value ?? null);
      return null;
    }
    if (method === "host.storageDelete") {
      this.requirePermission("host.storage");
      if (!this.api.storageDelete) throw new Error("Host storage is unavailable");
      const input = requireRecord(params, "host.storageDelete params");
      await this.api.storageDelete(this.plugin.manifest.id, requireStorageKey(input.key));
      return null;
    }
    if (method === "host.openFloating") {
      // A floating window is a workbench surface in its own right, so it shares
      // the workbench permission gate instead of introducing a new one.
      this.requirePermission("host.workbench");
      if (!this.api.openFloatingWindow) throw new Error("Floating plugin windows require the desktop host");
      const request = parseFloatingWindowRequest(this.plugin.manifest.id, requireRecord(params, "host.openFloating params"));
      if (!this.ownWorkbenchContributionIds().has(request.contributionId)) throw new Error("Unknown workbench contribution");
      return this.api.openFloatingWindow(request);
    }
    if (method === "host.closeFloating") {
      if (!this.api.closeFloatingWindows) throw new Error("Floating plugin windows require the desktop host");
      const input = isRecord(params) ? params : {};
      const contributionId = optionalTrimmedString(input.contributionId);
      const own = this.ownWorkbenchContributionIds();
      if (contributionId && !own.has(contributionId)) throw new Error("Unknown workbench contribution");
      // Without an explicit contribution every floating window of this plugin
      // closes; labels are host-derived, so a plugin can never reach another
      // plugin's window (or the main shell) through this path.
      const contributionIds = contributionId ? [contributionId] : [...own];
      await this.api.closeFloatingWindows(contributionIds.map((id) => floatingWindowLabel(this.plugin.manifest.id, id)));
      return null;
    }
    if (method === "host.beginFloatingDrag") {
      if (!this.api.beginFloatingDrag) throw new Error("Floating plugin windows require the desktop host");
      await this.api.beginFloatingDrag();
      return null;
    }
    if (method === "host.endFloatingDrag") {
      if (!this.api.endFloatingDrag) throw new Error("Floating plugin windows require the desktop host");
      const input = isRecord(params) ? params : {};
      return (await this.api.endFloatingDrag(input.snap !== false)) ?? null;
    }
    if (method === "host.setFloatingSize") {
      if (!this.api.setFloatingSize) throw new Error("Floating plugin windows require the desktop host");
      const input = requireRecord(params, "host.setFloatingSize params");
      const width = requireFloatingDimension(input.width, "width");
      const height = requireFloatingDimension(input.height, "height");
      await this.api.setFloatingSize(width, height);
      return null;
    }
    throw new Error(`Unsupported plugin host method '${method}'`);
  }

  /** The plugin's own declared workbench contributions — the only ones it may host in a floating window. */
  private ownWorkbenchContributionIds(): Set<string> {
    return new Set((this.plugin.manifest.contributions || []).filter((candidate) => candidate.type === "workbench").map((candidate) => candidate.id));
  }

  private async requireClipboardRead(): Promise<number> {
    const now = Date.now();
    if (!clipboardReadGateAllows(this.clipboardReadGate, now)) {
      recordClipboardRead(this.clipboardReadGate, now, "rate-limited", 0);
      throw new Error("Clipboard read rate limit exceeded; retry in a moment");
    }
    if (this.clipboardReadGate.consented === null) {
      const answer = this.api.confirmClipboardRead ? await this.api.confirmClipboardRead(this.plugin.manifest.id, this.plugin.manifest.name) : false;
      this.clipboardReadGate.consented = answer === true;
      if (!this.clipboardReadGate.consented) {
        recordClipboardRead(this.clipboardReadGate, now, "denied", 0);
        throw new Error("Clipboard read was denied for this plugin session");
      }
    }
    return now;
  }

  private requirePermission(permission: string): void {
    if (!this.hasPermission(permission)) throw new Error(`Plugin has not declared permission '${permission}'`);
  }

  /** Resolves once the user allowed this plugin to read `connectionId`; rejects on denial. */
  private async ensureDataAccess(connectionId: string): Promise<void> {
    const known = this.dataAccess.get(connectionId);
    if (known === "granted") return;
    if (known === "denied") throw new Error("Data access to this connection was denied for this plugin session");
    let pending = this.pendingDataAccess.get(connectionId);
    if (!pending) {
      pending = this.requestDataAccess(connectionId).finally(() => this.pendingDataAccess.delete(connectionId));
      this.pendingDataAccess.set(connectionId, pending);
    }
    await pending;
  }

  private async requestDataAccess(connectionId: string): Promise<void> {
    const pluginId = this.plugin.manifest.id;
    if (this.api.hasDataGrant && (await this.api.hasDataGrant(pluginId, connectionId))) {
      this.dataAccess.set(connectionId, "granted");
      return;
    }
    // A host that cannot ask denies; it never grants silently.
    const allowed = this.api.confirmDataAccess && this.api.grantDataAccess ? (await this.api.confirmDataAccess(pluginId, this.plugin.manifest.name, connectionId)) === true : false;
    if (!allowed || !this.api.grantDataAccess) {
      this.dataAccess.set(connectionId, "denied");
      throw new Error("Data access to this connection was denied");
    }
    await this.api.grantDataAccess(pluginId, connectionId);
    this.dataAccess.set(connectionId, "granted");
  }

  private hasPermission(permission: string): boolean {
    const permissions = this.plugin.manifest.permissions || [];
    if (permissions.includes(permission)) return true;
    if (permission === PLUGIN_CONNECTIONS_READ_PERMISSION && permissions.includes("host.connections::read")) {
      return true;
    }
    return false;
  }

  private respond(target: Window, id: string, payload: { result?: unknown; error?: string }): void {
    target.postMessage({ source: HOST_MESSAGE_SOURCE, version: BRIDGE_VERSION, type: "response", id, ...payload }, "*");
  }

  private post(message: Record<string, unknown>): void {
    this.targetWindow()?.postMessage(message, "*");
  }
}

/**
 * Parse `host.network:<origin>` permission entries into CSP connect-src
 * origins. Must stay aligned with `parse_host_network_permission` in
 * crates/dbx-plugin-runtime/src/plugins/manifest.rs.
 */
export function pluginNetworkOrigins(permissions: readonly string[] | undefined): string[] {
  const origins = new Set<string>();
  for (const permission of permissions || []) {
    if (!permission.startsWith("host.network:")) continue;
    const origin = permission.slice("host.network:".length);
    if (!/^https:\/\/[A-Za-z0-9._-]+(?::[0-9]+)?$/.test(origin)) continue;
    origins.add(origin);
    if (origins.size >= 8) break;
  }
  return [...origins];
}

export interface PluginSandboxOptions {
  /**
   * Base URL for plugin UI resources resolved relative to the srcdoc document
   * (for example, inlined CSS `url()` references) — `dbx-plugin://localhost/<id>/`
   * on native custom schemes, `http(s)://dbx-plugin.localhost/<id>/` where
   * WebView2 maps the scheme to an http subdomain. Injected as the document
   * `<base>` and allowed in resource CSP directives. External module imports
   * resolve from their own preserved URLs. Omit on hosts without the plugin
   * asset protocol (the web host).
   */
  baseUrl?: string;
  /**
   * Adds `'unsafe-eval'` to `script-src`. WebGL graphics engines codegen their
   * uniform sync with `new Function` and refuse to initialize without it, so
   * the user grants this per plugin (see `pluginGraphicsEngine.ts`). Off by
   * default: the sandbox stays eval-free for every other plugin.
   */
  allowUnsafeEval?: boolean;
}

export function pluginSandboxDocument(html: string, permissions?: readonly string[], theme?: PluginBridgeTheme, options?: PluginSandboxOptions): string {
  const networkOrigins = pluginNetworkOrigins(permissions);
  const connectSrc = networkOrigins.length > 0 ? `connect-src ${networkOrigins.join(" ")};` : "connect-src 'none';";
  const assetSource = pluginAssetCspSource(options?.baseUrl);
  const scriptSrc = options?.allowUnsafeEval ? "script-src 'unsafe-inline' 'unsafe-eval'" : "script-src 'unsafe-inline'";
  const csp = `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; ${scriptSrc} blob:${assetSource}; style-src 'unsafe-inline' blob:; img-src data: blob:${assetSource}; font-src data: blob:${assetSource}; ${connectSrc} media-src data: blob:${assetSource};">`;
  // <base> must precede relative URLs resolved from the srcdoc itself (such as
  // inlined CSS url() references), so it leads the injection.
  const base = options?.baseUrl && assetSource ? `<base href="${escapeHtmlAttribute(options.baseUrl)}">` : "";
  const sdk = `<script>${pluginSdkSource(theme)}</script>`;
  const uiKit = `<style>${pluginUiKitCss()}</style>`;
  // Placed after the uiKit so the boot `color-scheme` wins the cascade: the
  // bridge init message (and the SDK's applyTheme) only runs once the iframe
  // has loaded, and the uiKit's token fallbacks would otherwise paint the
  // first frame white on dark hosts.
  const bootTheme = pluginBootThemeCss(theme);
  const injection = `${csp}${base}${uiKit}${bootTheme ? `<style>${bootTheme}</style>` : ""}${sdk}`;
  if (/<head(?:\s[^>]*)?>/i.test(html)) return html.replace(/<head(?:\s[^>]*)?>/i, (head) => `${head}${injection}`);
  return `<!doctype html><html><head>${injection}</head><body>${html}</body></html>`;
}

/**
 * CSP source expression for the plugin asset base URL: the exact origin for
 * the http(s)-mapped form (WebView2), the whole scheme for the native custom
 * scheme form. Only dbx-plugin shapes contribute a source — anything else is
 * ignored (and suppresses the <base> too).
 */
function pluginAssetCspSource(baseUrl: string | undefined): string {
  if (!baseUrl) return "";
  const mapped = baseUrl.match(/^(https?:\/\/dbx-plugin\.localhost)(?:\/|$)/i);
  if (mapped) return ` ${mapped[1].toLowerCase()}`;
  return /^dbx-plugin:\/\//i.test(baseUrl) ? " dbx-plugin:" : "";
}

function escapeHtmlAttribute(value: string): string {
  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
}

/**
 * Pre-paint theme seed for the sandbox document. The bridge init message only
 * arrives after the iframe load event, so without this style the first frame
 * renders with the uiKit fallbacks (white background) before the real tokens
 * land — the white flash when opening a plugin workbench on a dark host.
 */
export function pluginBootThemeCss(theme?: PluginBridgeTheme): string {
  if (!theme || (theme.appearance !== "dark" && theme.appearance !== "light")) return "";
  const declarations: string[] = [`color-scheme: ${theme.appearance}`];
  const tokens = theme.tokens && typeof theme.tokens === "object" ? theme.tokens : {};
  for (const [name, value] of Object.entries(tokens)) {
    // Same name validation as the SDK's applyTheme; values must stay inside a
    // single CSS declaration so they cannot break out of the style element.
    if (!/^--[a-z0-9-]+$/i.test(name) || typeof value !== "string" || !value.trim()) continue;
    if (!/^[^"{}<>;]*$/.test(value)) continue;
    declarations.push(`${name}: ${value}`);
  }
  return `:root{${declarations.join(";")}}`;
}

/**
 * Minimal official component kit for plugin workbenches. Every class is built
 * on the DBX design tokens the host pushes through the bridge, so plugin UI
 * follows light/dark and palette changes without any plugin-side logic.
 */
export function pluginUiKitCss(): string {
  return `
:root { color-scheme: light dark; }
* { box-sizing: border-box; }
body {
  margin: 0;
  font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif);
  font-size: 13px;
  line-height: 1.5;
  color: var(--color-foreground, #18181b);
  background: var(--color-background, #ffffff);
}
.dbx-card {
  border: 1px solid var(--color-border, #e4e4e7);
  border-radius: var(--radius-lg, 10px);
  background: var(--color-card, #ffffff);
  padding: 14px 16px;
}
.dbx-section-title {
  font-size: 11px;
  font-weight: 600;
  letter-spacing: 0.04em;
  text-transform: uppercase;
  color: var(--color-muted-foreground, #71717a);
  margin: 0 0 10px;
}
.dbx-btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 6px;
  height: 30px;
  padding: 0 12px;
  border-radius: var(--radius-md, 8px);
  border: 1px solid var(--color-border, #d4d4d8);
  background: var(--color-background, #ffffff);
  color: var(--color-foreground, #18181b);
  font-size: 13px;
  cursor: pointer;
}
.dbx-btn:hover { background: var(--color-muted, #f4f4f5); }
.dbx-btn--primary { background: var(--color-primary, #2563eb); border-color: var(--color-primary, #2563eb); color: var(--color-primary-foreground, #ffffff); }
.dbx-btn--primary:hover { background: var(--color-primary, #2563eb); opacity: 0.9; }
.dbx-btn--danger { background: var(--color-destructive, #dc2626); border-color: var(--color-destructive, #dc2626); color: var(--color-destructive-foreground, #ffffff); }
.dbx-btn--ghost { border-color: transparent; background: transparent; }
.dbx-btn:disabled { opacity: 0.5; cursor: not-allowed; }
.dbx-label { display: inline-flex; font-size: 12px; font-weight: 500; color: var(--color-foreground, #18181b); }
.dbx-input, .dbx-select, .dbx-textarea {
  width: 100%;
  height: 30px;
  padding: 0 10px;
  border-radius: var(--radius-md, 8px);
  border: 1px solid var(--color-input, #d4d4d8);
  background: var(--color-background, #ffffff);
  color: var(--color-foreground, #18181b);
  font-size: 13px;
  font-family: inherit;
}
.dbx-textarea { height: auto; min-height: 64px; padding: 6px 10px; resize: vertical; }
.dbx-input:focus, .dbx-select:focus, .dbx-textarea:focus { outline: 2px solid var(--color-ring, #93c5fd); outline-offset: 1px; border-color: var(--color-ring, #93c5fd); }
.dbx-hint { font-size: 12px; color: var(--color-muted-foreground, #71717a); }
.dbx-row { display: grid; grid-template-columns: minmax(96px, auto) minmax(0, 1fr); gap: 8px 12px; align-items: center; margin-bottom: 10px; }
.dbx-table { width: 100%; border-collapse: collapse; font-size: 12px; }
.dbx-table th { text-align: left; font-weight: 600; color: var(--color-muted-foreground, #71717a); border-bottom: 1px solid var(--color-border, #e4e4e7); padding: 6px 8px; }
.dbx-table td { border-bottom: 1px solid var(--color-border, #e4e4e7); padding: 6px 8px; }
.dbx-badge { display: inline-flex; align-items: center; height: 20px; padding: 0 8px; border-radius: 999px; background: var(--color-primary-alpha, rgba(37, 99, 235, 0.12)); color: var(--color-primary, #2563eb); font-size: 11px; font-weight: 500; }
.dbx-link { color: var(--color-primary, #2563eb); text-decoration: none; cursor: pointer; }
.dbx-link:hover { text-decoration: underline; }
`.trim();
}

export function pluginSdkSource(initialTheme?: PluginBridgeTheme): string {
  const safeTokens = Object.fromEntries(Object.entries(initialTheme?.tokens || {}).filter(([name, value]) => /^--[a-z0-9-]+$/i.test(name) && typeof value === "string" && !!value.trim() && /^[^"{}<>;]*$/.test(value)));
  const safeInitialTheme = initialTheme && (initialTheme.appearance === "dark" || initialTheme.appearance === "light") ? { appearance: initialTheme.appearance, tokens: safeTokens } : null;
  const serializedInitialTheme = JSON.stringify(safeInitialTheme)
    .replace(/</g, "\\u003c")
    .replace(/>/g, "\\u003e")
    .replace(/\u2028/g, "\\u2028")
    .replace(/\u2029/g, "\\u2029");
  return `(() => {
    const pending = new Map();
    const listeners = { event: new Set(), binary: new Set(), init: new Set(), context: new Set(), filedrop: new Set(), dragstate: new Set(), close: new Set() };
    let sequence = 0;
    let contributionId;
    let context;
    let locale = 'en';
    let theme;
    let capabilities = {};
    let resolveReady;
    const initialTheme = ${serializedInitialTheme};
    const applyTheme = (value) => {
      if (!value || typeof value !== 'object') return;
      theme = value;
      const root = document.documentElement;
      root.dataset.dbxTheme = theme.appearance === "dark" ? "dark" : "light";
      root.style.colorScheme = theme.appearance === "dark" ? "dark" : "light";
      const tokens = value.tokens && typeof value.tokens === 'object' ? value.tokens : {};
      for (const [name, tokenValue] of Object.entries(tokens)) {
        if (/^--[a-z0-9-]+$/i.test(name) && typeof tokenValue === 'string') root.style.setProperty(name, tokenValue);
      }
    };
    const ready = new Promise((resolve) => { resolveReady = resolve; });
    if (initialTheme) applyTheme(initialTheme);
    // Plugin UIs routinely hand reactive state (Vue Proxy arrays/objects)
    // straight to invoke(); postMessage cannot structured-clone a Proxy and
    // WebKit rejects with "The object can not be cloned.". Mirror the host's
    // structuredCloneSafe: clone when possible, otherwise recover the plain
    // data with a JSON round-trip (the sidecar transport is JSON anyway).
    const toPlain = (value) => {
      if (!value || typeof value !== 'object') return value;
      if (typeof structuredClone === 'function') {
        try { return structuredClone(value); } catch {}
      }
      return JSON.parse(JSON.stringify(value));
    };
    const request = (method, params, options = {}) => new Promise((resolve, reject) => {
      const id = String(++sequence);
      pending.set(id, { resolve, reject });
      const message = { source: '${PLUGIN_MESSAGE_SOURCE}', version: ${BRIDGE_VERSION}, type: 'request', id, method, params: toPlain(params) };
      if (options.transfer) {
        message.data = options.transfer;
        parent.postMessage(message, '*', [options.transfer]);
      } else {
        parent.postMessage(message, '*');
      }
    });
    const decode = (value) => Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
    const encode = (value) => {
      const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
      let binary = '';
      for (const byte of bytes) binary += String.fromCharCode(byte);
      return btoa(binary);
    };
    const stream = async (method, params = {}, options = {}) => {
      const streamId = options.streamId || (globalThis.crypto?.randomUUID?.() || 'stream-' + Date.now() + '-' + (++sequence));
      const closeMethod = options.closeMethod || 'filesystem/stream/close';
      let removeListener;
      let closeRequested = false;
      let resolveOpen;
      let rejectOpen;
      const metadata = {};
      const opened = new Promise((resolve, reject) => { resolveOpen = resolve; rejectOpen = reject; });
      const readable = new ReadableStream({
        start(controller) {
          const onEvent = (message) => {
            if (message?.method !== 'host.stream.chunk' && message?.method !== 'host.stream.end' && message?.method !== 'host.stream.error') return;
            const event = message.params || {};
            if (event.streamId !== streamId) return;
            if (message.method === 'host.stream.chunk') {
              try { controller.enqueue(decode(event.dataBase64 || '')); } catch (error) { controller.error(error); }
              return;
            }
            removeListener?.();
            removeListener = undefined;
            if (message.method === 'host.stream.error') {
              const error = new Error(event.message || 'Plugin stream failed');
              rejectOpen(error);
              controller.error(error);
            } else {
              Object.assign(metadata, event);
              controller.close();
            }
          };
          removeListener = () => listeners.event.delete(onEvent);
          listeners.event.add(onEvent);
          request('backend.invoke', { method, params: { ...(params || {}), streamId }, timeoutMs: options.timeoutMs }).then(resolveOpen, (error) => {
            removeListener?.();
            removeListener = undefined;
            rejectOpen(error);
            controller.error(error);
          });
        },
        cancel() {
          removeListener?.();
          removeListener = undefined;
          if (closeRequested) return undefined;
          closeRequested = true;
          return request('backend.invoke', { method: closeMethod, params: { streamId } }).catch(() => undefined);
        },
      });
      Object.assign(metadata, await opened);
      return { stream: readable, metadata };
    };
    window.dbxPlugin = Object.freeze({
      ready,
      get contributionId() { return contributionId; },
      get context() { return context; },
      get locale() { return locale; },
      get theme() { return theme; },
      get capabilities() { return capabilities; },
      downloadFile: (options) => request('host.downloadFile', options),
      cancelDownload: (downloadId) => request('host.cancelDownload', { downloadId }),
      request,
      ai: Object.freeze({
        listProviders: () => request('host.ai.listProviders'),
        discoverModels: (configId) => request('host.ai.discoverModels', {configId}),
        listModels: () => request('host.ai.listModels'),
        generateText: (options) => request('host.ai.generateText', options),
        // E1 streaming: chunk events arrive as host.ai.generationChunk, filter
        // them by options.requestId via onEvent; the promise resolves with the
        // full text when the stream finishes. Gate on capabilities.aiCompletionStream.
        generateTextStream: (options) => request('host.ai.generateTextStream', options),
        // Cancels one active streamed generation by its requestId; resolves
        // { cancelled: boolean } and only ever touches this workbench's streams.
        cancelGeneration: (requestId) => request('host.ai.cancelGeneration', { requestId }),
        openConversation: (options) => request('host.ai.openConversation', options),
        setRecommendations: (update) => request('host.ai.setRecommendations', update),
        clearRecommendations: () => request('host.ai.clearRecommendations'),
      }),
      invoke: (method, params, options = {}) => request('backend.invoke', { method, params, timeoutMs: options.timeoutMs }),
      stream,
      notify: (method, params) => request('backend.notify', { method, params }),
      sendBinary: (channel, data) => {
        if (typeof data === 'string') return request('backend.sendBinary', { channel, dataBase64: data });
        const bytes = data instanceof ArrayBuffer ? data : (data instanceof Uint8Array ? data.buffer : new Uint8Array(data).buffer);
        return request('backend.sendBinary', { channel }, { transfer: bytes });
      },
      readAsset: (path) => request('ui.readAsset', { path }),
      readAssetUrl: async (path) => {
        const asset = await request('ui.readAsset', { path });
        return URL.createObjectURL(new Blob([decode(asset.dataBase64)], { type: asset.contentType }));
      },
      openWorkbench: (contributionId, childContext, options) => request('host.openWorkbench', { contributionId, context: childContext, forceNew: !!(options && options.forceNew), target: options && options.target === "tab" ? "tab" : undefined }),
      setTitle: (title) => request('host.setTitle', { title }),
      getTitle: () => request('host.getTitle'),
      // Closes whatever surface hosts this plugin UI — a workbench tab, a dock
      // entry, or this plugin's floating window. Same path as the Ctrl+W
      // shortcut, so a plugin can offer its own close/minimize affordance.
      closeWorkbench: () => parent.postMessage({ source: '${PLUGIN_MESSAGE_SOURCE}', version: ${BRIDGE_VERSION}, type: 'shortcut', shortcut: 'closeTab' }, '*'),
      // Floating desktop widget windows (the "window" surface): a frameless,
      // always-on-top window that stays visible over other applications. Gate on
      // capabilities.floating — a web host, or a desktop host without window
      // support, omits it and the plugin should fall back to tab or dock.
      //
      // Dragging is split by design: the plugin decides WHEN a drag starts
      // (thresholds, which element is a grip) and the host owns the movement —
      // beginDrag hands the window to the OS move loop, and the host snaps it
      // onto the work-area edges and remembers the spot once the loop goes
      // quiet. Per-move coordinates are deliberately not part of the protocol:
      // once the window follows the pointer, the webview's pointer capture is
      // cancelled and the move stream dies mid-drag.
      floating: Object.freeze({
        open: (options) => request('host.openFloating', options || {}),
        close: (contributionId) => request('host.closeFloating', { contributionId }),
        beginDrag: () => request('host.beginFloatingDrag'),
        endDrag: (options) => request('host.endFloatingDrag', options || {}),
        setSize: (width, height) => request('host.setFloatingSize', { width, height }),
      }),
      // §4/§5 command execution from a webview — the same registry path a menu
      // placement takes (enablement, §4.1 reuse, host-authored context),
      // scoped to the plugin's own declared commands. The optional context
      // merges over the command context and scopes instance_key placeholders
      // (e.g. one panel per connection). Resolves { error } for expected
      // business outcomes so callers can surface a notice without try/catch.
      // NOTE: this block is the sandbox bootstrap template source — comments
      // here must not contain backticks or dollar-brace interpolation.
      executeCommand: (commandId, context) => request('host.executeCommand', { commandId, context }),
      openFilesystem: (providerId, childContext) => request('host.openFilesystem', { providerId, context: childContext }),
      reopenConnection: (connectionId) => request('host.reopenConnection', { connectionId }),
      getConnections: () => request('host.getConnections', {}),
      listConnections: (options) => request('host.listConnections', options || {}),
      connections: Object.freeze({
        list: (options) => request('host.listConnections', options || {}),
        getAll: () => request('host.getConnections', {}),
      }),
      // Estimated plans only: mode must be sent explicitly so a plugin states
      // its intent, and the host refuses anything other than "estimated".
      getPlanCapabilities: (connectionId) => request('host.getPlanCapabilities', { connectionId }),
      explainPlan: (planRequest) => request('host.explainPlan', planRequest),
      // Read-only metadata; the host enforces the permission and open-session gate.
      getTableMetadata: (tableContext) => request('host.getTableMetadata', tableContext),
      // One read-only statement on a connection the user granted to this
      // plugin (host.data:read); the first query per connection asks the user.
      queryData: (dataRequest) => request('host.queryData', dataRequest),
      saveFile: (options = {}, data) => {
        if (data === undefined) return request('host.saveFile', options);
        if (typeof data === 'string') return request('host.saveFile', { ...(options || {}), dataBase64: data });
        const bytes = data instanceof ArrayBuffer ? data : (data instanceof Uint8Array ? data.buffer : new Uint8Array(data).buffer);
        return request('host.saveFile', options, { transfer: bytes });
      },
      copy: (text) => request('host.copy', { text }),
      // System clipboard surface: writeText rides the ungated host.copy path,
      // readText is served by host.clipboardRead and requires the plugin to
      // declare the host.clipboard:read permission (the bridge rejects
      // otherwise, and capabilities.clipboardRead advertises support).
      clipboard: Object.freeze({
        writeText: (text) => request('host.copy', { text }),
        readText: async () => {
          const result = await request('host.clipboardRead');
          return (result && typeof result === 'object' && typeof result.text === 'string') ? result.text : '';
        },
        readImage: async () => request('host.clipboardReadImage'),
      }),
      media: Object.freeze({
        open: async (method, params) => {
          const result = await request('host.mediaOpen', { method, params });
          const token = result && typeof result === 'object' && typeof result.token === 'string' ? result.token : '';
          if (!token) throw new Error('Host returned an invalid media token');
          return { token, url: new URL('__media/' + encodeURIComponent(token), document.baseURI).href };
        },
        close: (token) => request('host.mediaClose', { token }),
      }),
      // Persistent per-plugin key-value state; gate on capabilities.storage
      // (older hosts omit it) and declare the host.storage permission.
      storage: Object.freeze({
        get: (key) => request('host.storageGet', { key }),
        set: (key, value) => request('host.storageSet', { key, value: value === undefined ? null : value }),
        delete: (key) => request('host.storageDelete', { key }),
      }),
      fileTransfer: Object.freeze({
        pick: (options) => request('host.pickFiles', options || {}),
        read: (handleId, offset, length) => request('host.readFileChunk', { handleId, offset, length }),
        beginSave: (options) => request('host.beginFileSave', options || {}),
        write: (handleId, offset, data) => {
          if (typeof data === 'string') return request('host.writeFileChunk', { handleId, offset, dataBase64: data });
          // A Uint8Array can be a view into a larger buffer — transferring
          // .buffer blindly would send bytes outside the view. Copy the
          // visible range into a standalone ArrayBuffer first: the transfer
          // list only accepts ArrayBuffer/MessagePort (a Uint8Array view is
          // rejected by the engine with "Value at index 0 does not have a
          // transferable type", which failed every fileTransfer.write).
          const bytes = data instanceof ArrayBuffer ? data : (data instanceof Uint8Array ? data.slice().buffer : new Uint8Array(data).buffer);
          return request('host.writeFileChunk', { handleId, offset }, { transfer: bytes });
        },
        finish: (handleId) => request('host.finishFileSave', { handleId }),
        cancel: (handleId) => request('host.closeFileHandle', { handleId }),
        onDragState: (listener) => { listeners.dragstate.add(listener); return () => listeners.dragstate.delete(listener); },
        onDrop: (listener) => { listeners.filedrop.add(listener); return () => listeners.filedrop.delete(listener); },
      }),
      onEvent: (listener) => { listeners.event.add(listener); return () => listeners.event.delete(listener); },
      onBinary: (listener) => { listeners.binary.add(listener); return () => listeners.binary.delete(listener); },
      onContext: (listener) => { listeners.context.add(listener); return () => listeners.context.delete(listener); },
      onInit: (listener) => { listeners.init.add(listener); if (context !== undefined) listener(context); return () => listeners.init.delete(listener); },
      // §8.3 workbench/close handshake: the host sends workbench/close before
      // tearing the webview down; the plugin releases its workbench scope (PTY
      // sessions, subscriptions) in the listeners and the SDK acks once every
      // listener has settled. The host bounds the wait on its side.
      workbench: Object.freeze({
        onClose: (listener) => { listeners.close.add(listener); return () => listeners.close.delete(listener); },
        setTitle: (title) => request('host.setTitle', { title }),
        getTitle: () => request('host.getTitle'),
      }),
      decodeBase64: decode,
      encodeBase64: encode,
    });
    addEventListener('message', (event) => {
      if (event.source !== parent || !event.data || event.data.source !== '${HOST_MESSAGE_SOURCE}' || event.data.version !== ${BRIDGE_VERSION}) return;
      const message = event.data;
      if (message.type === 'response') {
        const handler = pending.get(message.id);
        if (!handler) return;
        pending.delete(message.id);
        if (message.error) handler.reject(new Error(message.error)); else handler.resolve(message.result);
      } else if (message.type === 'init') {
        contributionId = message.contributionId;
        capabilities = message.capabilities || {};
        context = message.context;
        locale = typeof message.locale === 'string' ? message.locale : 'en';
        applyTheme(message.theme);
        resolveReady(context);
        listeners.init.forEach((listener) => listener(context));
        // Plugin listeners register on the document (onHostThemeChange);
        // bare dispatchEvent targets window, which document listeners never
        // receive — env theme pushes were silently lost.
        document.dispatchEvent(new CustomEvent('dbx-plugin-init', { detail: message }));
      } else if (message.type === 'context') {
        context = message.context;
        listeners.context.forEach((listener) => listener(context));
        document.dispatchEvent(new CustomEvent('dbx-plugin-context', { detail: context }));
      } else if (message.type === 'env') {
        if (typeof message.locale === 'string') locale = message.locale;
        if (message.theme) applyTheme(message.theme);
        listeners.event.forEach((listener) => listener(message));
        document.dispatchEvent(new CustomEvent('dbx-plugin-env', { detail: message }));
      } else if (message.type === 'event') {
        listeners.event.forEach((listener) => listener(message));
        document.dispatchEvent(new CustomEvent('dbx-plugin-event', { detail: message }));
      } else if (message.type === 'binary') {
        const payload = { channel: message.channel, data: message.data ? new Uint8Array(message.data) : new Uint8Array(0) };
        listeners.binary.forEach((listener) => listener(payload));
        document.dispatchEvent(new CustomEvent('dbx-plugin-binary', { detail: payload }));
      } else if (message.type === 'filedrop') {
        const files = Array.isArray(message.files) ? message.files : [];
        const position = (message.position && typeof message.position.x === 'number' && typeof message.position.y === 'number')
          ? { x: message.position.x, y: message.position.y }
          : undefined;
        // The drop metadata rides as a second listener argument so existing
        // single-parameter listeners keep working unchanged.
        const drop = {
          dropId: typeof message.dropId === 'string' ? message.dropId : undefined,
          truncated: message.truncated === true,
          position,
        };
        listeners.filedrop.forEach((listener) => listener(files, drop));
        document.dispatchEvent(new CustomEvent('dbx-plugin-filedrop', { detail: { files, drop } }));
      } else if (message.type === 'dragstate') {
        const active = message.active === true;
        const position = (message.position && typeof message.position.x === 'number' && typeof message.position.y === 'number')
          ? { x: message.position.x, y: message.position.y }
          : undefined;
        listeners.dragstate.forEach((listener) => listener(active, position));
        document.dispatchEvent(new CustomEvent('dbx-plugin-dragstate', { detail: active }));
      } else if (message.type === 'workbench/close') {
        const notifyClose = (listener) => Promise.resolve().then(listener).catch(() => undefined);
        Promise.allSettled([...listeners.close].map(notifyClose)).finally(() => {
          const workbenchId = context && typeof context.workbenchId === 'string' ? context.workbenchId : '';
          parent.postMessage({ source: '${PLUGIN_MESSAGE_SOURCE}', version: ${BRIDGE_VERSION}, type: 'workbench/close-ack', workbenchId }, '*');
        });
      }
    });
    // The close-tab shortcut listens in the BUBBLE phase and yields to events a
    // plugin input already consumed. A capture-phase listener runs before the
    // focused control, so a terminal (xterm) handling Ctrl+W as "delete word"
    // had the tab closed underneath it: the host posted closeTab before the
    // terminal ever saw the key. Bubbling lets the focused control run first;
    // xterm calls preventDefault()+stopPropagation() for the keys it sends, and
    // any other consumer only needs preventDefault() to keep the tab open.
    addEventListener('keydown', (event) => {
      if (event.defaultPrevented) return;
      const key = typeof event.key === 'string' ? event.key.toLowerCase() : '';
      if (key !== 'w' || (!event.metaKey && !event.ctrlKey) || event.altKey || event.shiftKey || event.isComposing) return;
      event.preventDefault();
      event.stopPropagation();
      parent.postMessage({ source: '${PLUGIN_MESSAGE_SOURCE}', version: ${BRIDGE_VERSION}, type: 'shortcut', shortcut: 'closeTab' }, '*');
    });
    parent.postMessage({ source: '${PLUGIN_MESSAGE_SOURCE}', version: ${BRIDGE_VERSION}, type: 'ready', features: ['workbench.close'] }, '*');
  })();`;
}

function validRequestMessage(value: Record<string, unknown>): value is Record<string, unknown> & PluginRequestMessage {
  return typeof value.id === "string" && value.id.length > 0 && value.id.length <= 128 && typeof value.method === "string" && value.method.length > 0 && value.method.length <= 128;
}

function requireRecord(value: unknown, label: string): Record<string, unknown> {
  if (!isRecord(value)) throw new Error(`${label} must be an object`);
  return value;
}

/** A host-owned AI task preset (E3): the enum is closed, so unknown values fail here. */
function requirePluginAiTask(value: unknown): PluginAiTask {
  if (typeof value !== "string" || !PLUGIN_AI_TASKS.includes(value as PluginAiTask)) throw new Error("Invalid AI task");
  return value as PluginAiTask;
}

function requireProtocolName(value: unknown, label: string): string {
  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/.test(value)) throw new Error(`${label} is invalid`);
  return value;
}

function requireTimeout(value: unknown): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("timeoutMs must be a number");
  return Math.min(120_000, Math.max(1, Math.round(value)));
}

/** A connection id, database, or schema name: bounded, trimmed, never empty. */
function requirePluginPlanIdentifier(value: unknown, label: string): string {
  if (typeof value !== "string") throw new Error(`${label} must be a string`);
  const identifier = value.trim();
  if (!identifier) throw new Error(`${label} must not be empty`);
  if (identifier.length > MAX_PLUGIN_PLAN_IDENTIFIER_CHARS) {
    throw new Error(`${label} must be at most ${MAX_PLUGIN_PLAN_IDENTIFIER_CHARS} characters`);
  }
  return identifier;
}

function optionalPluginPlanScope(value: unknown, label: string): string | undefined {
  if (value === undefined || value === null) return undefined;
  if (typeof value !== "string") throw new Error(`${label} must be a string`);
  return value.trim() ? requirePluginPlanIdentifier(value, label) : undefined;
}

function requirePluginTableContext(input: Record<string, unknown>): PluginTableContext {
  const context: PluginTableContext = {
    connectionId: requirePluginSchemaMetadataIdentifier(input.connectionId, "connectionId"),
    table: requirePluginSchemaMetadataIdentifier(input.table, "table"),
  };
  const database = optionalPluginSchemaMetadataIdentifier(input.database, "database");
  const schema = optionalPluginSchemaMetadataIdentifier(input.schema, "schema");
  if (database !== undefined) context.database = database;
  if (schema !== undefined) context.schema = schema;
  return context;
}

function requirePluginSchemaMetadataIdentifier(value: unknown, label: string): string {
  if (typeof value !== "string") throw new Error(`${label} must be a string`);
  const identifier = value.trim();
  if (!identifier) throw new Error(`${label} must not be empty`);
  if (Array.from(identifier).length > MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS) {
    throw new Error(`${label} must be at most ${MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS} characters`);
  }
  return identifier;
}

function optionalPluginSchemaMetadataIdentifier(value: unknown, label: string): string | undefined {
  if (value === undefined || value === null) return undefined;
  if (typeof value !== "string") throw new Error(`${label} must be a string`);
  return value.trim() ? requirePluginSchemaMetadataIdentifier(value, label) : undefined;
}

/**
 * Validates one `host.explainPlan` request. The host owns the EXPLAIN text, so
 * the only accepted shape is the caller's own SQL plus a connection reference
 * and an explicit `estimated` mode; anything else is refused here rather than
 * forwarded and downgraded. The backend re-checks every one of these bounds.
 */
function requirePluginPlanRequest(input: Record<string, unknown>): PluginPlanRequest {
  if (input.mode !== "estimated") throw new Error('host.explainPlan serves mode "estimated" only');
  if (typeof input.sql !== "string") throw new Error("host.explainPlan requires sql");
  const sql = input.sql.trim();
  if (!sql) throw new Error("host.explainPlan requires a non-empty sql");
  if (sql.length > MAX_PLUGIN_PLAN_SQL_CHARS) {
    throw new Error(`sql must be at most ${MAX_PLUGIN_PLAN_SQL_CHARS} characters`);
  }

  const request: PluginPlanRequest = {
    connectionId: requirePluginPlanIdentifier(input.connectionId, "connectionId"),
    sql,
    mode: "estimated",
  };
  const database = optionalPluginPlanScope(input.database, "database");
  if (database !== undefined) request.database = database;
  const schema = optionalPluginPlanScope(input.schema, "schema");
  if (schema !== undefined) request.schema = schema;
  if (input.timeoutMs !== undefined && input.timeoutMs !== null) {
    request.timeoutMs = clampPluginPlanTimeout(input.timeoutMs);
  }
  return request;
}

/**
 * Validates one `host.queryData` request: a connection reference, optional
 * scope, one SQL text, and optional bounds. The backend re-checks every bound
 * and owns the read-only decision; this only refuses malformed input early.
 */
function requirePluginDataQueryRequest(input: Record<string, unknown>): PluginDataQueryRequest {
  if (typeof input.sql !== "string") throw new Error("host.queryData requires sql");
  const sql = input.sql.trim();
  if (!sql) throw new Error("host.queryData requires a non-empty sql");
  if (sql.length > MAX_PLUGIN_DATA_SQL_CHARS) throw new Error(`sql must be at most ${MAX_PLUGIN_DATA_SQL_CHARS} characters`);
  const request: PluginDataQueryRequest = { connectionId: requirePluginDataName(input.connectionId, "connectionId"), sql };
  for (const key of ["database", "schema"] as const) {
    const value = input[key];
    if (value === undefined || value === null) continue;
    if (typeof value !== "string") throw new Error(`${key} must be a string`);
    if (value.trim()) request[key] = requirePluginDataName(value, key);
  }
  if (input.maxRows !== undefined && input.maxRows !== null) {
    if (typeof input.maxRows !== "number" || !Number.isFinite(input.maxRows)) throw new Error("maxRows must be a number");
    request.maxRows = Math.min(MAX_PLUGIN_DATA_MAX_ROWS, Math.max(1, Math.floor(input.maxRows)));
  }
  if (input.timeoutMs !== undefined && input.timeoutMs !== null) {
    if (typeof input.timeoutMs !== "number" || !Number.isFinite(input.timeoutMs)) throw new Error("timeoutMs must be a number");
    request.timeoutMs = Math.min(MAX_PLUGIN_DATA_TIMEOUT_MS, Math.max(1, Math.round(input.timeoutMs)));
  }
  return request;
}

function requirePluginDataName(value: unknown, label: string): string {
  if (typeof value !== "string") throw new Error(`${label} must be a string`);
  const name = value.trim();
  if (!name) throw new Error(`${label} must not be empty`);
  if (Array.from(name).length > MAX_PLUGIN_DATA_NAME_CHARS) throw new Error(`${label} must be at most ${MAX_PLUGIN_DATA_NAME_CHARS} characters`);
  return name;
}

/** Pre-clamps to the host ceiling; the backend additionally clamps to the connection's own timeout. */
function clampPluginPlanTimeout(value: unknown): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("timeoutMs must be a number");
  return Math.min(MAX_PLUGIN_PLAN_TIMEOUT_MS, Math.max(1, Math.round(value)));
}

function requireHandleId(value: unknown): string {
  if (typeof value !== "string" || !value || value.length > 128) throw new Error("handleId is invalid");
  return value;
}

function requirePluginAiRecommendationUpdate(value: unknown): PluginAiRecommendationUpdate {
  const input = requireRecord(value, "AI recommendation update");
  if (!isRecord(input.context)) throw new Error("AI recommendation context must be an object");
  if (!Array.isArray(input.items)) throw new Error("AI recommendation items must be an array");
  if (input.items.length > 5) throw new Error("At most 5 AI recommendations may be registered");
  const context = snapshotPluginWorkbenchContext(input.context) as PluginAiRecommendationContext;
  const items = input.items.map((candidate, index) => {
    if (!isRecord(candidate)) throw new Error(`AI recommendation ${index} must be an object`);
    if (typeof candidate.id !== "string" || !candidate.id.trim()) throw new Error(`AI recommendation ${index} requires id`);
    if (typeof candidate.label !== "string" || !candidate.label.trim() || candidate.label.length > 200) throw new Error(`AI recommendation ${index} label is invalid`);
    if (typeof candidate.prompt !== "string" || !candidate.prompt.trim() || candidate.prompt.length > 32000) throw new Error(`AI recommendation ${index} prompt is invalid`);
    if (!isValidPluginAiRecommendationTemplate(candidate.label) || !isValidPluginAiRecommendationTemplate(candidate.prompt)) throw new Error(`AI recommendation ${index} contains an invalid placeholder`);
    if (candidate.order !== undefined && (typeof candidate.order !== "number" || !Number.isFinite(candidate.order))) throw new Error(`AI recommendation ${index} order is invalid`);
    return {
      id: candidate.id.trim(),
      label: candidate.label.trim(),
      prompt: candidate.prompt.trim(),
      ...(candidate.order === undefined ? {} : { order: candidate.order }),
    };
  });
  return { context, items };
}

function requireOffset(value: unknown): number {
  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error("offset is invalid");
  return Math.floor(value);
}

function requireChunkLength(value: unknown): number {
  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new Error("length is invalid");
  return Math.min(8 * 1024 * 1024, Math.floor(value));
}

/** A `host.storage` key: bounded, non-empty, no control characters. */
function requireStorageKey(value: unknown): string {
  if (typeof value !== "string" || !value || value.length > MAX_PLUGIN_STORAGE_KEY_CHARS || /[\u0000-\u001f]/.test(value)) {
    throw new Error("storage key is invalid");
  }
  return value;
}

/** A floating window dimension in logical pixels; the host clamps it to its own bounds. */
function requireFloatingDimension(value: unknown, label: string): number {
  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new Error(`${label} must be a positive number`);
  return value;
}

function base64ToBytes(value: string): ArrayBuffer {
  const binary = atob(value);
  const bytes = new Uint8Array(binary.length);
  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
  return bytes.buffer;
}

function bytesToBase64(bytes: Uint8Array): string {
  let binary = "";
  const chunkSize = 0x8000;
  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
  }
  return btoa(binary);
}

function requireBase64(value: unknown): string {
  if (typeof value !== "string" || value.length > MAX_BRIDGE_PAYLOAD_BYTES * 2 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) throw new Error("Binary payload must be base64");
  return value;
}

function optionalTrimmedString(value: unknown): string | undefined {
  return typeof value === "string" && value.trim() ? value.trim() : undefined;
}

function requireSafeAssetPath(value: unknown): string {
  if (typeof value !== "string" || !value || value.startsWith("/") || value.split("/").some((part) => !part || part === "." || part === "..")) throw new Error("Plugin asset path is invalid");
  return value;
}

function enforcePayloadLimit(value: unknown): void {
  if (value === undefined) return;
  const bytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
  if (bytes > MAX_BRIDGE_PAYLOAD_BYTES) throw new Error("Plugin bridge request is too large");
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}