busa-sdk 0.14.1 → 0.16.0

package/dist/airapp-gate.css

@@ -0,0 +1,296 @@
+/**
+ * Default styling for the AirApp connect gate (`busabase-sdk/airapp-gate`).
+ *
+ * Ported from the stylesheet 62 App-in-Skills carried as a byte-identical copy,
+ * minus the rules left over from the retired setup-gate (secret rows, ready
+ * pills, prompt blocks) that the gate never rendered.
+ *
+ * Every value an app is likely to want to change is a custom property, so an
+ * app themes the gate by overriding these on `:root` instead of forking the
+ * file — that is the whole reason this can live in the SDK without dictating
+ * anyone's design system.
+ *
+ *   :root { --bb-gate-accent: #7c3aed; --bb-gate-radius: 14px; }
+ *
+ * Load it however the app loads CSS:
+ *   <link rel="stylesheet" href="./vendor/airapp-gate.css">
+ */
+
+:root {
+  --bb-gate-accent: #1570ef;
+  --bb-gate-accent-contrast: #fff;
+  --bb-gate-accent-wash: #f5f9ff;
+  --bb-gate-surface: #fff;
+  --bb-gate-surface-muted: #f9fafb;
+  --bb-gate-text: #17202a;
+  --bb-gate-text-strong: #101828;
+  --bb-gate-text-muted: #667085;
+  --bb-gate-text-label: #344054;
+  --bb-gate-border: #d0d5dd;
+  --bb-gate-border-subtle: #eaecf0;
+  --bb-gate-danger: #b42318;
+  --bb-gate-scrim: color-mix(in srgb, #101828 72%, transparent);
+  --bb-gate-radius: 8px;
+  --bb-gate-radius-inner: 6px;
+  --bb-gate-font: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+
+html.bb-gate-active,
+html.bb-gate-active body {
+  overflow: hidden;
+}
+
+.bb-gate-overlay {
+  position: fixed;
+  inset: 0;
+  /* Below the max z-index so an app's own toast/portal layer can still sit on
+     top if it deliberately opts to. */
+  z-index: 2147483000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: var(--bb-gate-scrim);
+  font-family: var(--bb-gate-font);
+  color: var(--bb-gate-text);
+}
+
+.bb-gate-panel {
+  width: min(720px, 100%);
+  max-height: min(760px, calc(100vh - 48px));
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  overflow: hidden;
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius);
+  box-shadow: 0 24px 64px rgb(16 24 40 / 28%);
+}
+
+.bb-gate-head {
+  display: flex;
+  gap: 24px;
+  align-items: start;
+  justify-content: space-between;
+  padding: 22px 24px 18px;
+  border-bottom: 1px solid var(--bb-gate-border-subtle);
+}
+
+.bb-gate-head h1 {
+  margin: 0;
+  font-size: 22px;
+  line-height: 1.25;
+  letter-spacing: 0;
+}
+
+.bb-gate-head p {
+  margin: 6px 0 0;
+  color: var(--bb-gate-text-muted);
+  font-size: 14px;
+}
+
+.bb-gate-body {
+  overflow: auto;
+  padding: 20px 24px;
+}
+
+.bb-gate-body h2 {
+  margin: 0 0 12px;
+  font-size: 14px;
+  letter-spacing: 0;
+}
+
+.bb-gate-server-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.bb-gate-server-card {
+  min-height: 104px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 16px;
+  text-align: left;
+  color: var(--bb-gate-text-label);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: 7px;
+  cursor: pointer;
+}
+
+.bb-gate-server-card:hover {
+  border-color: var(--bb-gate-text-muted);
+}
+
+.bb-gate-server-card.is-selected {
+  border-color: var(--bb-gate-accent);
+  box-shadow: inset 0 0 0 1px var(--bb-gate-accent);
+  background: var(--bb-gate-accent-wash);
+}
+
+.bb-gate-server-card input {
+  flex: none;
+  margin: 0;
+}
+
+.bb-gate-server-card > span {
+  display: grid;
+  gap: 2px;
+}
+
+.bb-gate-server-card strong {
+  font-size: 15px;
+}
+
+.bb-gate-server-card span span {
+  color: var(--bb-gate-text-muted);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.bb-gate-custom-url {
+  display: grid;
+  gap: 6px;
+  margin-top: 16px;
+  padding: 16px;
+  border: 1px solid var(--bb-gate-border-subtle);
+  border-radius: 7px;
+  background: var(--bb-gate-surface-muted);
+  color: var(--bb-gate-text-label);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.bb-gate-custom-url[hidden] {
+  display: none;
+}
+
+.bb-gate-custom-url input {
+  min-width: 0;
+  min-height: 38px;
+  padding: 8px 10px;
+  color: var(--bb-gate-text-strong);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius-inner);
+  font: inherit;
+  font-weight: 400;
+}
+
+.bb-gate-space-select {
+  display: grid;
+  gap: 6px;
+  margin-top: 14px;
+  color: var(--bb-gate-text-label);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.bb-gate-space-select select {
+  min-height: 38px;
+  padding: 8px 10px;
+  color: var(--bb-gate-text-strong);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius-inner);
+  font: inherit;
+  font-weight: 400;
+}
+
+.bb-gate-error {
+  color: var(--bb-gate-danger);
+  font-size: 13px;
+}
+
+.bb-gate-note {
+  color: var(--bb-gate-text-muted);
+}
+
+.bb-gate-link {
+  color: var(--bb-gate-accent);
+  font-size: 13px;
+  font-weight: 650;
+  text-decoration: none;
+}
+
+.bb-gate-link:hover {
+  text-decoration: underline;
+}
+
+.bb-gate-footer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 10px;
+  padding: 14px 24px;
+  border-top: 1px solid var(--bb-gate-border-subtle);
+  background: var(--bb-gate-surface);
+}
+
+.bb-gate-footer button {
+  min-height: 38px;
+  padding: 0 14px;
+  color: var(--bb-gate-text-label);
+  background: var(--bb-gate-surface);
+  border: 1px solid var(--bb-gate-border);
+  border-radius: var(--bb-gate-radius-inner);
+  font-weight: 650;
+  cursor: pointer;
+}
+
+.bb-gate-footer .bb-gate-primary {
+  color: var(--bb-gate-accent-contrast);
+  background: var(--bb-gate-accent);
+  border-color: var(--bb-gate-accent);
+}
+
+.bb-gate-footer button:disabled {
+  opacity: 0.55;
+  cursor: wait;
+}
+
+@media (max-width: 600px) {
+  .bb-gate-overlay {
+    align-items: stretch;
+    padding: 0;
+  }
+
+  .bb-gate-panel {
+    width: 100%;
+    max-height: 100vh;
+    border: 0;
+    border-radius: 0;
+  }
+
+  .bb-gate-head {
+    padding: 18px 16px 14px;
+  }
+
+  .bb-gate-head h1 {
+    font-size: 19px;
+  }
+
+  .bb-gate-head p {
+    font-size: 13px;
+  }
+
+  .bb-gate-body {
+    padding: 16px;
+  }
+
+  .bb-gate-server-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .bb-gate-footer {
+    padding: 12px 16px;
+  }
+
+  .bb-gate-footer button {
+    min-width: 0;
+    flex: 1;
+    padding-inline: 8px;
+  }
+}

package/dist/airapp-gate.d.ts

@@ -0,0 +1,157 @@
+import { BusabaseAirAppAuthStatus } from './airapp-node.js';
+import './oauth-node.js';
+import './oauth.js';
+
+/**
+ * The AirApp connect gate — the browser half of local onboarding.
+ *
+ * `busabase-sdk/airapp-node` already owns the *flow* (PKCE, credential
+ * rotation, Space validation, the `/api/v1` proxy). This module owns the
+ * remaining copy-paste: deciding which of the three screens to show, and
+ * drawing them. 62 App-in-Skills carried a 160-line renderer whose only
+ * per-app difference was the display name interpolated into an HTML string,
+ * plus a byte-identical 290-line stylesheet — while the app-creator template
+ * grew a second, differently-classed implementation of the same three screens.
+ *
+ * Structure, deliberately: every decision and every piece of markup is a pure
+ * function of the gateway's status. The DOM is touched only in `mount` /
+ * `wire`. That is what makes the escaping (the one security-relevant part —
+ * `oauth_error` and Space names both come from outside) testable without a
+ * browser, and what lets an app swap the renderer without reimplementing the
+ * state machine.
+ *
+ * Import `busabase-sdk/airapp-gate.css` (or copy it) for the default look; it
+ * is themed entirely through custom properties.
+ *
+ * @example
+ * ```ts
+ * import { createAirAppConnectGate } from "busabase-sdk/airapp-gate";
+ *
+ * const gate = createAirAppConnectGate({
+ *   appName: "Kelly CRM",
+ *   onProvision: () => provider.provisionResources(),
+ * });
+ *
+ * // Before mounting the app shell:
+ * if (await gate.pass({ onReady: () => start() })) start();
+ *
+ * // When loading data fails because the workspace is not set up yet:
+ * gate.renderSetupRequired(error, () => start());
+ * ```
+ */
+
+/** Which screen the gate owes the operator right now. */
+type AirAppGateScreen = "connect" | "space" | "ready";
+/**
+ * Decide the screen from the gateway's status. Headless — a custom renderer
+ * should call this rather than re-deriving the rules from `connected`.
+ *
+ * Driven by `readiness`, with a fallback to the older `connected` /
+ * `requiresSpace` pair so an app can upgrade the SDK before its server.
+ */
+declare function selectAirAppGateScreen(status: Partial<BusabaseAirAppAuthStatus> | null | undefined): AirAppGateScreen;
+/** The five setup states, decoded into what the workspace screen needs to know. */
+interface AirAppSetupDescription {
+    code: string;
+    /** The message with its `CODE: ` prefix stripped. */
+    detail: string;
+    title: string;
+    /** Offer an "Initialize workspace" button. */
+    canProvision: boolean;
+    /** Offer a "Check again" button (the app cannot act; the operator can retry). */
+    canRetry: boolean;
+}
+/**
+ * Decode a setup failure. Accepts an `AirAppSetupError`, any `Error` whose
+ * message uses the historical `"CODE: detail"` shape, or a bare string — the
+ * generated apps throw all three spellings.
+ */
+declare function describeAirAppSetupError(error: unknown): AirAppSetupDescription;
+interface AirAppGateOptions {
+    /** Shown in the gate's prose, e.g. "Kelly CRM". The one per-app value. */
+    appName: string;
+    /**
+     * Where to mount. A selector, an element, or omitted to create and prepend
+     * `#busabaseAirAppGate` to `<body>`.
+     */
+    mount?: string | HTMLElement;
+    /** Prefix for the gateway routes; `""` means `/auth/status`, `/auth/start`, … */
+    authBasePath?: string;
+    /**
+     * Whether this run owes a gate at all. Return `false` for a Busabase-hosted
+     * AirApp (the ambient session owns auth) or for a demo/offline mode.
+     *
+     * **Pass this.** Omitted, `pass()` falls back to probing `/auth/status` and
+     * treating an unreachable or non-JSON answer as "hosted" — which works, but
+     * infers something the host already states outright. A Busabase-hosted AirApp
+     * is identified by the `BUSABASE_AIRAPP_RUNTIME` env var Busabase injects into
+     * the process it spawns, surfaced to the browser by the app's own server;
+     * never by hostname, iframe nesting, or path, since a hosted AirApp can be
+     * served from localhost and a standalone run can be reached over a dev tunnel.
+     */
+    shouldGate?: () => boolean | Promise<boolean>;
+    /** Injected for tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Called by the workspace screen's "Initialize workspace" button. */
+    onProvision?: () => Promise<unknown>;
+    /** Where the "open the demo" escape hatch points. Omit to hide it. */
+    demoHref?: string | null;
+    /** Replace the default markup wholesale while keeping the state machine. */
+    render?: AirAppGateRenderer;
+}
+interface AirAppGateRenderer {
+    connect(view: AirAppConnectView): string;
+    space(view: AirAppSpaceView): string;
+    workspace(view: AirAppWorkspaceView): string;
+}
+interface AirAppConnectView {
+    appName: string;
+    cloudBaseUrl: string;
+    /** Set when the operator is here because the session lapsed, not first-run. */
+    reconnect: boolean;
+    /** `?oauth_error=` from the callback redirect. Untrusted. */
+    oauthError: string;
+    authBasePath: string;
+}
+interface AirAppSpaceView {
+    appName: string;
+    baseUrl: string;
+    spaces: {
+        id: string;
+        name: string;
+    }[];
+}
+interface AirAppWorkspaceView extends AirAppSetupDescription {
+    appName: string;
+    demoHref: string | null;
+}
+/** HTML-escape. Every interpolation below goes through this. */
+declare const escapeHtml: (value: unknown) => string;
+/** The stock three screens. Pure string builders — no DOM, no fetch. */
+declare const defaultAirAppGateRenderer: AirAppGateRenderer;
+declare const DEFAULT_CLOUD_BASE_URL = "https://busabase.com";
+interface AirAppConnectGate {
+    /**
+     * Resolve the gate before the app shell mounts. `true` means the app may
+     * load data; `false` means a screen is up and waiting on the operator — call
+     * again after `onReady` fires.
+     */
+    pass(options?: {
+        onReady?: () => void;
+    }): Promise<boolean>;
+    /** Show the workspace screen for a setup error thrown while loading data. */
+    renderSetupRequired(error: unknown, onRetry: () => void): void;
+    /** Take the gate down and give scrolling back to the page. */
+    close(): void;
+    /** Fetch the gateway's status without rendering anything. */
+    status(): Promise<BusabaseAirAppAuthStatus | null>;
+}
+/**
+ * Build a gate bound to one app.
+ *
+ * Nothing is rendered until `pass()` decides a screen is owed, so it is safe to
+ * construct at module scope.
+ */
+declare function createAirAppConnectGate(options: AirAppGateOptions): AirAppConnectGate;
+
+export { type AirAppConnectGate, type AirAppConnectView, type AirAppGateOptions, type AirAppGateRenderer, type AirAppGateScreen, type AirAppSetupDescription, type AirAppSpaceView, type AirAppWorkspaceView, BusabaseAirAppAuthStatus, DEFAULT_CLOUD_BASE_URL, createAirAppConnectGate, defaultAirAppGateRenderer, describeAirAppSetupError, escapeHtml, selectAirAppGateScreen };

package/dist/airapp-gate.js

@@ -0,0 +1,238 @@
+// src/airapp-gate.ts
+function selectAirAppGateScreen(status) {
+  if (!status) return "connect";
+  switch (status.readiness) {
+    case "needs_connection":
+    case "needs_auth":
+      return "connect";
+    case "needs_space":
+      return "space";
+    case "ready":
+      return "ready";
+  }
+  if (!status.connected) return "connect";
+  return status.requiresSpace ? "space" : "ready";
+}
+function describeAirAppSetupError(error) {
+  const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : "";
+  const raw = String(
+    (typeof error === "object" && error !== null && "message" in error ? error.message : error) ?? "SETUP_REQUIRED"
+  );
+  const parsed = /^([A-Z_]+):\s*(.*)$/s.exec(raw);
+  const resolvedCode = code || parsed?.[1] || raw.trim() || "SETUP_REQUIRED";
+  const detail = parsed ? parsed[2] : code ? raw : "";
+  const pending = resolvedCode === "SETUP_PENDING";
+  const canProvision = resolvedCode === "SETUP_REQUIRED";
+  return {
+    code: resolvedCode,
+    detail,
+    title: pending ? "Waiting for workspace approval" : canProvision ? "Initialize the Busabase workspace" : "Workspace not ready",
+    canProvision,
+    canRetry: resolvedCode === "SETUP_PENDING" || resolvedCode === "SCHEMA_INCOMPLETE"
+  };
+}
+var escapeHtml = (value) => String(value ?? "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#039;");
+var panel = (labelledBy, head, body, footer) => `<div class="bb-gate-overlay"><section class="bb-gate-panel" role="dialog" aria-modal="true" aria-labelledby="${labelledBy}"><div class="bb-gate-head"><div>${head}</div></div><div class="bb-gate-body">${body}</div><div class="bb-gate-footer">${footer}</div></section></div>`;
+var defaultAirAppGateRenderer = {
+  connect(view) {
+    const head = `<h1 id="bbGateConnectTitle">Connect Busabase</h1><p>${escapeHtml(view.appName)} reads and writes through your Busabase workspace.</p>`;
+    const body = (view.oauthError ? `<p class="bb-gate-error" role="alert">${escapeHtml(view.oauthError)}</p>` : "") + (view.reconnect ? `<p class="bb-gate-note">Your session expired. Reconnect to continue.</p>` : "") + `<h2>Server</h2><div class="bb-gate-server-grid"><label class="bb-gate-server-card is-selected"><input type="radio" name="server_mode" value="cloud" checked><span><strong>Busabase Cloud</strong><span>${escapeHtml(hostOf(view.cloudBaseUrl))}</span></span></label><label class="bb-gate-server-card"><input type="radio" name="server_mode" value="custom"><span><strong>Custom server</strong><span>Self-hosted or enterprise address</span></span></label></div><label class="bb-gate-custom-url" data-custom-url hidden><span>Busabase URL</span><input type="url" name="custom_base_url" inputmode="url" placeholder="https://busabase.example.com" autocomplete="url"></label><input type="hidden" name="base_url" value="${escapeHtml(view.cloudBaseUrl)}">`;
+    const footer = `<span class="bb-gate-note">OAuth credentials stay on this machine (~/.busabase/airapps)</span><button class="bb-gate-primary" type="submit">Connect Busabase</button>`;
+    return `<form method="post" action="${escapeHtml(`${view.authBasePath}/auth/start`)}" data-connect-form>${panel("bbGateConnectTitle", head, body, footer)}</form>`;
+  },
+  space(view) {
+    const options = view.spaces.map(
+      (space) => `<option value="${escapeHtml(space.id)}">${escapeHtml(space.name)} \xB7 ${escapeHtml(space.id)}</option>`
+    ).join("");
+    const head = `<h1 id="bbGateSpaceTitle">Choose a Busabase Space</h1><p>Signed in to <strong>${escapeHtml(view.baseUrl)}</strong>. Choose where ${escapeHtml(view.appName)}'s data lives.</p>`;
+    const body = `<label class="bb-gate-space-select"><span>Space</span><select name="space_id" required>${options}</select></label><p class="bb-gate-error" data-space-error hidden></p>`;
+    const footer = `<span class="bb-gate-note">Resources are only checked after you confirm</span><button class="bb-gate-primary" type="submit">Use this Space</button>`;
+    return `<form data-space-form>${panel("bbGateSpaceTitle", head, body, footer)}</form>`;
+  },
+  workspace(view) {
+    const head = `<h1 id="bbGateWorkspaceTitle">${escapeHtml(view.title)}</h1>`;
+    const body = view.canProvision ? `<p>${escapeHtml(view.appName)} will create its Folder and Bases in the current Space.</p><p>Submitted as one idempotent Busabase ChangeRequest; nothing existing is deleted or repurposed.</p><p class="bb-gate-error" data-workspace-status hidden></p>` : `<p>${escapeHtml(view.detail)}</p><p>${escapeHtml(view.appName)} never asks you to create Nodes or Bases by hand, and never silently falls back to local data.</p><p class="bb-gate-error" data-workspace-status hidden></p>`;
+    const footer = (view.demoHref ? `<a class="bb-gate-link" href="${escapeHtml(view.demoHref)}">Open the read-only demo</a>` : "<span></span>") + (view.canProvision ? `<button class="bb-gate-primary" type="button" data-provision>Initialize workspace</button>` : view.canRetry ? `<button class="bb-gate-primary" type="button" data-retry>Check again</button>` : "");
+    return panel("bbGateWorkspaceTitle", head, body, footer);
+  }
+};
+var hostOf = (baseUrl) => {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+};
+var DEFAULT_CLOUD_BASE_URL = "https://busabase.com";
+function createAirAppConnectGate(options) {
+  const {
+    appName,
+    authBasePath = "",
+    onProvision,
+    demoHref = null,
+    render = defaultAirAppGateRenderer
+  } = options;
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const root = () => {
+    if (options.mount) {
+      const element2 = typeof options.mount === "string" ? document.querySelector(options.mount) : options.mount;
+      if (!element2) throw new Error(`AirApp gate mount not found: ${String(options.mount)}`);
+      document.documentElement.classList.add("bb-gate-active");
+      return element2;
+    }
+    let element = document.querySelector("#busabaseAirAppGate");
+    if (!element) {
+      element = document.createElement("div");
+      element.id = "busabaseAirAppGate";
+      document.body.prepend(element);
+    }
+    document.documentElement.classList.add("bb-gate-active");
+    return element;
+  };
+  const close = () => {
+    if (options.mount) {
+      const element = typeof options.mount === "string" ? document.querySelector(options.mount) : options.mount;
+      if (element) element.innerHTML = "";
+    } else {
+      document.querySelector("#busabaseAirAppGate")?.remove();
+    }
+    document.documentElement.classList.remove("bb-gate-active");
+  };
+  const status = async () => {
+    try {
+      const response = await doFetch(`${authBasePath}/auth/status`, {
+        headers: { accept: "application/json" }
+      });
+      const type = response.headers.get("content-type") ?? "";
+      if (!response.ok || !type.includes("application/json")) return null;
+      return await response.json();
+    } catch {
+      return null;
+    }
+  };
+  const renderConnect = (current) => {
+    const element = root();
+    const oauthError = new URLSearchParams(window.location.search).get("oauth_error") ?? "";
+    element.innerHTML = render.connect({
+      appName,
+      cloudBaseUrl: current?.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL,
+      reconnect: current?.readiness === "needs_auth",
+      oauthError,
+      authBasePath
+    });
+    wireConnect(element, current?.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL);
+  };
+  const renderSpace = (current, onReady) => {
+    const element = root();
+    element.innerHTML = render.space({
+      appName,
+      baseUrl: current.baseUrl ?? "",
+      spaces: current.spaces ?? []
+    });
+    wireSpace(element, onReady);
+  };
+  const wireConnect = (element, cloudBaseUrl) => {
+    const form = element.querySelector("[data-connect-form]");
+    if (!form) return;
+    const customField = form.querySelector("[data-custom-url]");
+    const customInput = customField?.querySelector("input") ?? null;
+    const hiddenBaseUrl = form.querySelector('input[name="base_url"]');
+    for (const radio of form.querySelectorAll('input[name="server_mode"]')) {
+      radio.addEventListener("change", () => {
+        const custom = radio.value === "custom";
+        for (const card of form.querySelectorAll(".bb-gate-server-card")) {
+          card.classList.toggle("is-selected", card.querySelector("input")?.checked === true);
+        }
+        if (customField) customField.hidden = !custom;
+        if (customInput) customInput.required = custom;
+        if (hiddenBaseUrl) hiddenBaseUrl.value = custom ? customInput?.value ?? "" : cloudBaseUrl;
+        if (custom) customInput?.focus();
+      });
+    }
+    customInput?.addEventListener("input", () => {
+      if (hiddenBaseUrl) hiddenBaseUrl.value = customInput.value;
+    });
+  };
+  const wireSpace = (element, onReady) => {
+    const form = element.querySelector("[data-space-form]");
+    form?.addEventListener("submit", async (event) => {
+      event.preventDefault();
+      const button = form.querySelector("button[type=submit]");
+      const error = form.querySelector("[data-space-error]");
+      if (button) button.disabled = true;
+      if (error) error.hidden = true;
+      try {
+        const response = await doFetch(`${authBasePath}/auth/space`, {
+          method: "POST",
+          headers: { "content-type": "application/x-www-form-urlencoded" },
+          body: new URLSearchParams(new FormData(form))
+        });
+        const result = await response.json();
+        if (!response.ok) {
+          if (error) {
+            error.textContent = result.error || "Could not select a Space.";
+            error.hidden = false;
+          }
+          if (button) button.disabled = false;
+          return;
+        }
+        onReady();
+      } catch {
+        if (error) {
+          error.textContent = "Could not reach this app's server.";
+          error.hidden = false;
+        }
+        if (button) button.disabled = false;
+      }
+    });
+  };
+  const renderSetupRequired = (error, onRetry) => {
+    const element = root();
+    element.innerHTML = render.workspace({
+      ...describeAirAppSetupError(error),
+      appName,
+      demoHref
+    });
+    element.querySelector("[data-retry]")?.addEventListener("click", () => onRetry());
+    element.querySelector("[data-provision]")?.addEventListener("click", async (event) => {
+      const button = event.currentTarget;
+      const line = element.querySelector("[data-workspace-status]");
+      button.disabled = true;
+      if (line) {
+        line.hidden = false;
+        line.textContent = "Submitting the workspace structure\u2026";
+      }
+      try {
+        await onProvision?.();
+        onRetry();
+      } catch (provisionError) {
+        renderSetupRequired(provisionError, onRetry);
+      }
+    });
+  };
+  const pass = async ({ onReady } = {}) => {
+    if (options.shouldGate && !await options.shouldGate()) {
+      close();
+      return true;
+    }
+    const current = await status();
+    if (!current) return true;
+    const screen = selectAirAppGateScreen(current);
+    if (screen === "ready") {
+      close();
+      return true;
+    }
+    if (screen === "space") {
+      renderSpace(current, () => {
+        close();
+        onReady?.();
+      });
+      return false;
+    }
+    renderConnect(current);
+    return false;
+  };
+  return { pass, renderSetupRequired, close, status };
+}
+
+export { DEFAULT_CLOUD_BASE_URL, createAirAppConnectGate, defaultAirAppGateRenderer, describeAirAppSetupError, escapeHtml, selectAirAppGateScreen };