@netlify/spark-ui 1.31.0-alpha.5 → 1.31.0-alpha.6

package/README.md

@@ -147,13 +147,13 @@ This repo includes a [Claude Code](https://claude.ai/code) skill for generating
 
 The skill is available automatically. Run:
 
-```text
+```
 /project:landing-page <describe the page you want>
 ```
 
 For example:
 
-```text
+```
 /project:landing-page A landing page for a new enterprise hosting product with a hero, feature cards, and a pricing comparison
 ```
 
@@ -185,7 +185,7 @@ When you’re ready to validate your component changes in a deploy preview, you
 >
 > Reach out to #internal-permissions in Slack
 
-### Steps to Publish an Alpha Release
+### Steps to Publish an Alpha Release:
 
 1. **Make sure you're logged into npm locally**
 
@@ -206,7 +206,6 @@ When you’re ready to validate your component changes in a deploy preview, you
    ```
 
 1. **Install the updated package:**
-
    ```bash
    npm install
    ```

package/dist/components/preact/DropZone/DropZone.d.ts

@@ -10,29 +10,17 @@ interface Props {
     client?: DropClient;
     /** Build the "claim this site" URL from the assigned site name (subdomain). */
     claimUrl?: (siteName: string) => string;
-    /**
-     * Where an authenticated static deploy sends the visitor — the site already
-     * lives in their account, so there is no claim step. Defaults to the new
-     * site's project overview on app.netlify.com.
-     */
+    /** Destination after an authenticated static deploy (no claim step). Default: the project overview. */
     siteDashboardUrl?: (siteName: string) => string;
     /**
-     * The signup hand-off for a build-required drop that can't be built here (no
-     * session, or no build wiring). The drop is stashed on this origin first, so
-     * a flow that returns the visitor to this page deploys it automatically —
-     * see `resumeStashedBuilds`. Defaults to the app signup page with
-     * `next=/drop`.
+     * Signup hand-off for a build drop with no session. The drop is stashed on
+     * this origin first — return the visitor here and it deploys automatically.
      */
     buildSignupUrl?: string;
     /**
-     * Mint a short-lived bearer token for direct api.netlify.com uploads — pass it
-     * to switch on the whole authenticated path for logged-in visitors: static
-     * drops deploy straight into their account (then `siteDashboardUrl`), and
-     * build-required drops build in place instead of being handed off to the app.
-     * On netlify.com this reads `GET /access-control/generate-access-control-token`.
-     * Resolving `null` means "no session": static drops fall back to the anonymous
-     * claim flow; build drops are stashed and handed to `buildSignupUrl`.
-     * See [Logged-in visitors](#logged-in-visitors).
+     * Mint the upload bearer — passing this switches on the whole authenticated
+     * path. `null` means "no session": static drops fall back to the anonymous
+     * claim flow; build drops stash and hand off. See the docs' Logged-in visitors.
      */
     getUploadToken?: () => Promise<string | null>;
     /**
@@ -40,111 +28,49 @@ interface Props {
      * Takes precedence over `getUploadToken` for the build path.
      */
     buildClient?: BuildClient;
-    /**
-     * Inject a custom authenticated `DropClient` for static drops (tests, staging,
-     * a different account flow). Takes precedence over `getUploadToken` for the
-     * static path. Distinct from `client`, which is the anonymous fallback.
-     */
+    /** Custom authenticated static-drop client; wins over `getUploadToken`. (`client` is the anonymous fallback.) */
     authenticatedDropClient?: DropClient;
-    /**
-     * API root for the authenticated paths' JSON calls, which go through your
-     * access-control rewrite so the session cookie authorizes them. Defaults to
-     * `/access-control/bb-api/api/v1`. (Uploads always go direct to
-     * `api.netlify.com` — the proxy can't carry bodies that large.)
-     */
+    /** Root for the session-cookie JSON calls, via your access-control rewrite. Uploads always go direct. */
     proxyBase?: string;
     /** Create the visitor's new project in this account. Omit for their default account. */
     accountSlug?: string;
-    /**
-     * Where an enqueued build sends the visitor. Defaults to the new site's
-     * project overview, same as a static deploy; `build.deployId` is available for
-     * consumers who want the deploy-log page instead.
-     */
+    /** Destination after a build is enqueued. Default: the project overview (`build.deployId` for the logs page). */
     buildDeployUrl?: (build: DeployedBuild) => string;
     /**
-     * Poll until the build finishes before handing off, instead of redirecting as
-     * soon as it's enqueued. The trade-off: waiting means a failing build surfaces
-     * its own error message here (via `onError` and the overlay) rather than the
-     * visitor discovering it on the deploy page — at the cost of holding them on a
-     * spinner for the length of the build, which is minutes. Off by default.
+     * Hold the visitor until the build finishes (off by default — builds take
+     * minutes). On is the only way a failing build's own message reaches `onError`.
      */
     waitForBuild?: boolean;
-    /**
-     * Called when a build-required drop is detected, instead of building it or
-     * redirecting. Use it to own the hand-off yourself (custom routing, persisting
-     * the drop, gating on auth). When set, the component neither builds nor
-     * redirects. The static drop path is unaffected either way.
-     */
+    /** Take over build-required drops entirely — when set, the component neither builds nor redirects. */
     onBuildRequired?: (info: BuildDetection) => void;
     /**
-     * Called instead of the `buildSignupUrl` redirect when a build-required drop
-     * can't be built here (no session). By this point the drop has been stashed
-     * on this origin (`stashed` says whether that succeeded) — own the hand-off
-     * however fits your auth flow, e.g. open a signup popup that keeps the
-     * visitor on the page. Once they're back authenticated, a remount of the
-     * zone deploys the stash automatically.
+     * Own the signup hand-off instead of the `buildSignupUrl` redirect (e.g. an
+     * auth popup). The drop is already stashed; a remount while authenticated
+     * deploys it.
      */
     onBuildSignupHandoff?: (info: {
         stashed: boolean;
         detection: BuildDetection;
     }) => void;
-    /**
-     * Deploy a previously stashed build drop automatically when the zone mounts
-     * with an authenticated visitor (default `true`). The stash is written when a
-     * logged-out build drop is handed to signup; see
-     * [Signup hand-off and auto-resume](#signup-hand-off-and-auto-resume).
-     */
+    /** Auto-deploy a stashed build drop on mount when authenticated (default true). */
     resumeStashedBuilds?: boolean;
     /** Called once the deploy is live. */
     onDeploy?: (result: DeployedSite) => void;
-    /**
-     * Called once a build-required drop has been zipped, uploaded and enqueued —
-     * before the redirect to `buildDeployUrl`. The site exists at this point but
-     * won't serve content until the build finishes.
-     */
+    /** Called once a build is enqueued, before the `buildDeployUrl` redirect. */
     onBuildDeploy?: (build: DeployedBuild) => void;
-    /**
-     * Called when a deploy fails, with a humanized `message` (ready to show a
-     * user — the same copy the built-in overlay uses) and the raw `reason`. Pair
-     * this with `showStatus={false}` to render your own error UI.
-     */
+    /** Deploy failures: humanized `message` (the overlay's copy) + raw `reason`. Pair with showStatus={false}. */
     onError?: (error: DeployError) => void;
     /**
-     * Render the built-in status overlay (drag tint, spinner, progress bar, error).
-     * Set to `false` to suppress it entirely and keep your children visible, then
-     * drive your own feedback from the `data-state` attribute on the root element.
-     * Note: in this mode you're responsible for surfacing errors yourself — use
-     * `onError` to get the message.
+     * Render the built-in overlay. `false` keeps children visible — drive your
+     * own feedback from `data-state`, and surface errors yourself via `onError`.
      */
     showStatus?: boolean;
     /**
-     * Analytics hook. Called at each tracked moment with an event name and
-     * properties. Stays provider-agnostic — wire it to Segment/Amplitude/GA in the
-     * consuming app, e.g. `onTrack={(name, props) => new Analytics().track(name, props)}`.
-     * Emitted events (all include `dropzone_id` when `analyticsId` is set):
-     * - `dropzone_files_dropped`  — files dropped via drag  ({ method: 'drag', file_count, file_types })
-     * - `dropzone_browse_opened`  — file picker opened       ({ method: 'keyboard' | 'click' })
-     * - `dropzone_build_required` — drop needs a build (built here, or handed off) ({ method, reason, file_count, file_types })
-     * - `dropzone_deploy_succeeded` — static deploy went live ({ method, site_name, file_count, authenticated, auth_fallback?, file_types })
-     * - `dropzone_build_deploy_succeeded` — build enqueued for a logged-in visitor ({ method, reason, site_name, file_count, framework?, file_types })
-     * - `dropzone_deploy_failed`  — deploy or build errored out ({ method, reason, file_count?, file_types })
-     *
-     * `authenticated` says whether the deploy landed in the visitor's account;
-     * `auth_fallback: true` is sent only when an authenticated attempt bounced
-     * (stale auth hint) and the drop completed anonymously — omitted otherwise.
-     * `file_types` is the sorted, de-duplicated list of MIME types in the
-     * selection, with `application/octet-stream` standing in wherever the browser
-     * reports none (a dragged folder, an `.exe`). It is omitted when the browser
-     * exposes no files at all. Note `dropzone_files_dropped` only fires for drag —
-     * a file-picker selection reports its types on the outcome events, as
-     * `dropzone_browse_opened` fires before any file exists.
+     * Provider-agnostic analytics hook. Event names and payload shapes live in
+     * DROPZONE_EVENTS / DropZoneEventProperties (drop-core/analytics.ts).
      */
     onTrack?: TrackFn;
-    /**
-     * Stable identifier for this instance, attached to every tracked event as
-     * `dropzone_id`. Set it when a page renders more than one Drop Zone so the
-     * events can be told apart in Amplitude.
-     */
+    /** Stamped on every event as `dropzone_id` — set when a page has more than one zone. */
     analyticsId?: string;
     className?: string;
 }

package/dist/drop-core/analytics.d.ts

@@ -1,17 +1,10 @@
 import { BuildReason } from './detectBuild';
-/**
- * The Drop Zone's analytics contract — the canonical event names and property
- * shapes, exported so no consumer (this package's own component, a host site's
- * GTM wiring, or another Netlify surface implementing its own Drop UI over
- * drop-core) ever hand-writes the strings.
- */
+/** The analytics contract: canonical event names + property shapes, so no consumer hand-writes them. */
 /** How the files reached the zone — carried on every drop-initiated event as `method`. */
 export type DropMethod = 'drag' | 'browse';
 /**
- * Canonical Drop Zone lifecycle events. The values are the wire names:
- * analytics history in Amplitude/Segment keys off these exact strings, so
- * renaming a value silently forks every funnel built on it — treat them as
- * append-only.
+ * The wire names. Amplitude/Segment history keys off these exact strings —
+ * append-only, never rename.
  */
 export declare const DROPZONE_EVENTS: {
     /** Files arrived via drag — the picker path reports its files on outcome events instead. */
@@ -99,9 +92,5 @@ export interface DropZoneEventProperties {
     dropzone_project_stashed: ProjectStashedProps;
     dropzone_resumed: ResumedProps;
 }
-/**
- * Provider-agnostic analytics sink. Deliberately loose (string, not the event
- * union): hosts forward these to Segment/GA/GTM and often pipe their own
- * events through the same function.
- */
+/** Provider-agnostic sink — loose on purpose, since hosts pipe their own events through it too. */
 export type TrackFn = (event: string, properties?: Record<string, unknown>) => void;

package/dist/drop-core/authedApi.d.ts

@@ -1,20 +1,13 @@
 import { BuildSite } from './types';
 /**
- * The transport both authenticated clients share: JSON calls ride the
- * consumer's access-control rewrite on the session cookie, so nothing
- * credential-shaped lives in the browser and nothing can expire mid-deploy.
- * (Uploads are the exception — the proxy's Lambda caps request bodies at
- * ~6MB — and each client handles its own, bearer-authorized.)
+ * Transport shared by both authenticated clients: JSON rides the consumer's
+ * access-control rewrite on the session cookie. Uploads are each client's own
+ * (bearer-direct — the proxy can't carry them).
  */
 /**
- * Create a site in the visitor's account via `POST {proxyBase}/sites` (scoped
- * to `accountSlug` when given, else the user's default account), attributed
- * `created_via: 'drop'`.
- *
- * A logged-out visitor 401s here, before anything is created — the one
- * pre-mutation point where callers may still safely fall back to an anonymous
- * flow, which is why it maps to `NotAuthenticatedError`. Any other failure is
- * a `SiteCreateError` carrying the status.
+ * `POST {proxyBase}/sites`, attributed `created_via: 'drop'`. A logged-out
+ * visitor 401s here, before anything is created — the one point an anonymous
+ * fallback is still safe, hence NotAuthenticatedError.
  */
 export declare function createSiteInAccount(proxyBase: string, accountSlug?: string): Promise<BuildSite>;
 /** How a watched deploy ended. `errorMessage` is the API's own explanation, when it gave one. */
@@ -27,15 +20,9 @@ export type SettledDeploy = {
     outcome: 'timed-out';
 };
 /**
- * Poll `GET {proxyBase}/deploys/{deployId}` on the session cookie until the
- * deploy settles, and report how. Purely mechanical on purpose: each caller
- * maps the outcome onto its own error vocabulary (the drop client throws plain
- * errors `humanizeDropError` understands; the build client throws
- * `BuildFailedError`/`BuildTimeoutError`), so that knowledge stays next to the
- * class it belongs to.
- *
- * A non-ok poll response is skipped, not fatal — a transient proxy hiccup
- * shouldn't kill a deploy that is still progressing.
+ * Polls the deploy on the session cookie and reports the terminal outcome —
+ * callers map it onto their own error vocabulary. Non-ok reads are skipped,
+ * not fatal: a proxy hiccup shouldn't kill a progressing deploy.
  */
 export declare function pollDeployUntilSettled(options: {
     proxyBase: string;

package/dist/drop-core/authedDropClient.d.ts

@@ -1,27 +1,13 @@
 import { DropClient } from './client';
 import { Digest, DropResponse } from './types';
 export interface AuthenticatedDropClientConfig {
-    /**
-     * Base for JSON API calls, routed through the consumer's access-control
-     * rewrite so the session cookie authenticates them. On netlify.com that
-     * rewrite is `/access-control/*` → the app's access-control function, which
-     * makes `/access-control/bb-api/api/v1` the API root (the default here).
-     */
+    /** Root for session-cookie JSON calls, via the consumer's access-control rewrite. */
     proxyBase?: string;
-    /**
-     * Direct API base for the file uploads. The proxy above runs in a Lambda with
-     * a ~6MB request body limit, so file PUTs go straight to `api.netlify.com`
-     * (whose `/api/*` CORS policy allows any origin).
-     */
+    /** Direct base for file PUTs — the proxy's ~6MB Lambda body limit can't carry uploads. */
     apiBase?: string;
     /**
-     * Mint a bearer token for those direct uploads. On netlify.com this is
-     * `GET /access-control/generate-access-control-token`, whose
-     * `accessControlToken` the API decrypts back into the user's access token.
-     * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
-     *
-     * Called repeatedly, not once: the token issued to a non-app origin lives
-     * only 30 seconds, which a multi-file upload routinely outlasts.
+     * Mint the upload bearer; `null` means "no session". Called repeatedly —
+     * non-app origins get 30-second tokens, which an upload queue outlasts.
      */
     getUploadToken: () => Promise<string | null>;
     /** Create the site in this account. Omit to use the user's default account. */
@@ -32,25 +18,10 @@ export interface AuthenticatedDropClientConfig {
     timeoutMs?: number;
 }
 /**
- * Authenticated drop client for logged-in visitors. Unlike `AnonymousDropClient`
- * — which creates an account-less site the visitor must later claim — this
- * deploys straight into the visitor's account via the sites/deploys API,
- * mirroring what app.netlify.com does for a logged-in drag-and-drop deploy.
- * There is no claim step, so the caller should hand off to the site's dashboard
- * page rather than the claim page.
- *
- * Requests split across two hosts by necessity. JSON calls (create the site,
- * create the deploy, poll it) go through the consumer's access-control proxy on
- * the session cookie — no token involved, and nothing that can expire mid-deploy.
- * File uploads can't: the proxy caps bodies at ~6MB, so they go direct to
- * `api.netlify.com` with a bearer, re-minted as it ages (see `TOKEN_REUSE_MS`).
- *
- * Error-mapping invariant: only pre-mutation failures — a null upload token at
- * the gate, or a 401/403 creating the site — throw `NotAuthenticatedError`,
- * which is the signal the drop flow may safely retry anonymously. Once the site
- * exists, any auth failure throws a plain error instead: falling back at that
- * point would strand an empty site in the account *and* deploy a duplicate
- * anonymously.
+ * Deploys a static drop straight into a logged-in visitor's account — no claim
+ * step. JSON rides the cookie proxy; file PUTs go direct on a re-minted bearer.
+ * Invariant: NotAuthenticatedError only pre-mutation — after the site exists, a
+ * fallback would strand an empty site and deploy a duplicate.
  */
 export declare class AuthenticatedDropClient implements DropClient {
     private proxyBase;
@@ -67,27 +38,14 @@ export declare class AuthenticatedDropClient implements DropClient {
      */
     getToken(): Promise<string>;
     /**
-     * A token young enough to authorize an upload, minting a new one once the
-     * cached one nears its 30s expiry. A mint failure here is a plain `Error`,
-     * never `NotAuthenticatedError` — the site exists by now (class doc).
+     * A token younger than its 30s expiry. Mint failures here are plain Errors,
+     * never NotAuthenticatedError — the site exists by now (class doc).
      */
     private freshToken;
-    /**
-     * Two proxied calls: create the site in the visitor's account, then the
-     * deploy on it. Mapped into the anonymous `DropResponse` shape so
-     * `deployFiles` runs unchanged over either client.
-     */
+    /** Site + deploy via the proxy, mapped into `DropResponse` so `deployFiles` runs unchanged. */
     createDeploy(files: Digest, _token: string): Promise<DropResponse>;
-    /**
-     * Direct to `api.netlify.com` on a freshly-aged bearer — the threaded `token`
-     * is ignored because an upload queue easily outlives the 30 seconds it was
-     * minted with. PUT (not POST) so paths with "&" etc. work.
-     */
+    /** Direct on a fresh bearer (the threaded one has expired). PUT so paths with "&" work. */
     uploadFile(deployId: string, path: string, content: ArrayBuffer, _token: string): Promise<void>;
-    /**
-     * Poll the deploy through the proxy until it settles: resolve on `ready`,
-     * throw on `error`/`rejected`, throw on timeout. On the session cookie rather
-     * than a bearer, so a deploy taking minutes can't outlive its own credentials.
-     */
+    /** Polls on the session cookie, so a slow deploy can't outlive its own credentials. */
     waitUntilReady(deploy: DropResponse, _token: string): Promise<void>;
 }

package/dist/drop-core/authedDropClient.js

@@ -33,9 +33,8 @@ class B {
     return this.cachedToken = { value: e, mintedAt: Date.now() }, e;
   }
   /**
-   * A token young enough to authorize an upload, minting a new one once the
-   * cached one nears its 30s expiry. A mint failure here is a plain `Error`,
-   * never `NotAuthenticatedError` — the site exists by now (class doc).
+   * A token younger than its 30s expiry. Mint failures here are plain Errors,
+   * never NotAuthenticatedError — the site exists by now (class doc).
    */
   async freshToken() {
     const e = Date.now();
@@ -45,11 +44,7 @@ class B {
     if (!t) throw new Error("could not renew the upload token");
     return this.cachedToken = { value: t, mintedAt: e }, t;
   }
-  /**
-   * Two proxied calls: create the site in the visitor's account, then the
-   * deploy on it. Mapped into the anonymous `DropResponse` shape so
-   * `deployFiles` runs unchanged over either client.
-   */
+  /** Site + deploy via the proxy, mapped into `DropResponse` so `deployFiles` runs unchanged. */
   async createDeploy(e, t) {
     const o = await p(this.proxyBase, this.accountSlug), s = await fetch(`${this.proxyBase}/sites/${o.id}/deploys`, {
       method: "POST",
@@ -66,11 +61,7 @@ class B {
       required: n.required ?? []
     };
   }
-  /**
-   * Direct to `api.netlify.com` on a freshly-aged bearer — the threaded `token`
-   * is ignored because an upload queue easily outlives the 30 seconds it was
-   * minted with. PUT (not POST) so paths with "&" etc. work.
-   */
+  /** Direct on a fresh bearer (the threaded one has expired). PUT so paths with "&" work. */
   async uploadFile(e, t, o, s) {
     const n = await this.freshToken(), r = await fetch(`${this.apiBase}/deploys/${e}/files${t}`, {
       method: "PUT",
@@ -79,11 +70,7 @@ class B {
     });
     if (!r.ok) throw l(`upload ${t}`, r.status);
   }
-  /**
-   * Poll the deploy through the proxy until it settles: resolve on `ready`,
-   * throw on `error`/`rejected`, throw on timeout. On the session cookie rather
-   * than a bearer, so a deploy taking minutes can't outlive its own credentials.
-   */
+  /** Polls on the session cookie, so a slow deploy can't outlive its own credentials. */
   async waitUntilReady(e, t) {
     const o = await h({
       proxyBase: this.proxyBase,

package/dist/drop-core/buildClient.d.ts

@@ -2,7 +2,6 @@ import { BuildSite } from './types';
 export type { BuildSite } from './types';
 /** The subset of a Netlify Build returned by `POST /sites/{id}/builds`. */
 export interface BuildResponse {
-    /** build id */
     id: string;
     /** the deploy the build produces — present as soon as the build is enqueued */
     deploy_id?: string;
@@ -13,28 +12,14 @@ export interface BuildClient {
     waitUntilBuildReady(build: BuildResponse): Promise<void>;
 }
 export interface AuthenticatedBuildClientConfig {
-    /**
-     * Base for JSON API calls, routed through the consumer's access-control
-     * rewrite so the session cookie authenticates them. On netlify.com that
-     * rewrite is `/access-control/*` → the app's access-control function, which
-     * makes `/access-control/bb-api/api/v1` the API root (the default here).
-     */
+    /** Root for session-cookie JSON calls, via the consumer's access-control rewrite. */
     proxyBase?: string;
-    /**
-     * Direct API base for the zip upload. The proxy above runs in a Lambda with a
-     * ~6MB request body limit, so the multipart POST has to go straight to
-     * `api.netlify.com` (whose `/api/*` CORS policy allows any origin).
-     */
+    /** Direct base for the zip upload — the proxy's ~6MB Lambda body limit can't carry it. */
     apiBase?: string;
     /**
-     * Mint a bearer token for that direct upload. On netlify.com this is
-     * `GET /access-control/generate-access-control-token`, whose
-     * `accessControlToken` the API decrypts back into the user's access token.
-     * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
-     *
-     * Note the token issued to a non-app origin lives only 30 seconds. It is
-     * minted immediately before the upload, but a zip that takes longer than that
-     * to transfer will still be rejected mid-flight — see `createBuildFromZip`.
+     * Mint the upload bearer; `null` means "no session". Non-app origins get
+     * 30-second tokens — a zip slower than that fails mid-flight (see
+     * `createBuildFromZip`).
      */
     getUploadToken: () => Promise<string | null>;
     /** Create the site in this account. Omit to use the user's default account. */
@@ -47,16 +32,9 @@ export interface AuthenticatedBuildClientConfig {
     timeoutMs?: number;
 }
 /**
- * Authenticated drop client for projects that need a build. Unlike
- * `AnonymousDropClient` — which creates an account-less static site and can only
- * upload pre-built files — this creates a real site in the user's account and
- * hands buildbot a source archive to build, mirroring what app.netlify.com does
- * for a drag-and-drop build.
- *
- * Requests split across two hosts by necessity: JSON calls go through the
- * consumer's access-control proxy (cookie session, no token handling in the
- * browser), while the zip upload goes direct to `api.netlify.com` with a
- * short-lived bearer token because the proxy can't carry a body that large.
+ * Builds a drop in a logged-in visitor's account: create the site, hand
+ * buildbot the source zip. JSON rides the cookie proxy; the zip goes direct
+ * with a bearer (the proxy can't carry it).
  */
 export declare class AuthenticatedBuildClient implements BuildClient {
     private proxyBase;
@@ -67,35 +45,23 @@ export declare class AuthenticatedBuildClient implements BuildClient {
     private pollIntervalMs;
     private timeoutMs;
     constructor({ proxyBase, apiBase, getUploadToken, accountSlug, title, pollIntervalMs, timeoutMs, }: AuthenticatedBuildClientConfig);
-    /**
-     * Create the site the build deploys into. A logged-out visitor fails here,
-     * before anything is created — see `createSiteInAccount` for the error
-     * mapping that makes the signup fallback safe.
-     */
+    /** A logged-out visitor fails here, before anything is created (see `createSiteInAccount`). */
     createSite(): Promise<BuildSite>;
     /**
-     * Upload the source archive and enqueue a build. Direct to `api.netlify.com`
-     * (see the note on `apiBase`), authorized by a freshly minted bearer token.
-     * `Content-Type` is left unset on purpose so the browser adds the multipart
-     * boundary itself.
+     * One multipart request on a fresh 30s bearer — a slower zip fails mid-flight
+     * (the app origin gets 300s; raising ours is a platform-side change).
+     * Content-Type stays unset so the browser adds the multipart boundary.
      *
-     * Known ceiling: this is one request on a 30s token, and re-minting can't
-     * help once it is in flight. A zip that takes longer than that to upload will
-     * fail — the app origin gets 300s for exactly this reason, and lifting the
-     * limit for other origins is a platform-side change.
+     * Never NotAuthenticatedError, including for a 401: the site exists by the
+     * time this runs, so signalling "no session" would strand it and re-stash
+     * the drop for the next visit to strand another. `createSite` is the auth
+     * gate for this path.
      */
     createBuildFromZip(siteId: string, zip: File): Promise<BuildResponse>;
     /**
-     * Poll the build's deploy until it settles, mirroring
-     * `AnonymousDropClient.waitUntilReady` — resolve on `ready`, throw on
-     * `error`/`rejected`, throw on timeout. A build that hasn't been given a
-     * deploy id yet has nothing pollable, so it resolves immediately and the
-     * caller falls back to the site page.
-     *
-     * Optional in the drop flow, and off by default: a build takes minutes, so
-     * the useful hand-off is usually the project page rather than a spinner.
-     * Polling rides the session cookie, so it cannot outlive its credentials the
-     * way a 30s bearer would.
+     * Optional (a build takes minutes; the useful hand-off is the project page).
+     * Polls on the cookie, so it can't outlive its credentials; no deploy id yet
+     * means nothing pollable, so it resolves immediately.
      */
     waitUntilBuildReady(build: BuildResponse): Promise<void>;
 }