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

package/packages/drop-core/README.md

@@ -0,0 +1,91 @@
+# drop-core
+
+The framework-free engine behind the Drop Zone: reading a dropped folder/zip
+into deployable files, deciding whether it needs a build, and deploying it —
+anonymously (claim flow) or into a logged-in visitor's account — plus the
+stash that carries a build drop across the signup round-trip.
+
+Consumed three ways: by the Preact `DropZone` in this repo, by anything
+importing `@netlify/spark-ui/drop-core`, and eventually by other Netlify
+surfaces implementing their own Drop UI over the same core.
+
+## Conventions
+
+These follow the practices shared by the libraries doing our two jobs —
+react-dropzone/Uppy/FilePond on the component side, netlify-cli's deploy
+engine, @vercel/client, and tus-js-client on the pipeline side. Where we
+deliberately differ, that's recorded too, so it isn't re-litigated by accident.
+
+### Boundaries
+
+- **Nothing in `drop-core` may import from `preact`** (or any UI framework).
+  Anything that imports preact may not contain deploy/read/detect logic — it
+  adapts this package to a view, nothing more.
+- **The barrel is the public API.** Nothing is public unless `index.ts` names
+  it; `export *` is reserved for modules that are contracts in their entirety
+  (`types`, `errors`, `analytics`). New helpers default to private.
+- **Granular pure modules, one cohesive orchestrator.** Pure helpers get their
+  own small file named after what they export; the deploy orchestration stays
+  together in `deploy.ts` rather than fragmenting a state machine.
+- **Shared tunables live in `constants.ts`** with a unit-bearing comment each
+  (`// 10 minutes`, not `// the timeout`). Module-specific constants stay with
+  their module. No magic numbers inline.
+
+### Naming
+
+| Kind               | Convention                         | Examples here                                                 |
+| ------------------ | ---------------------------------- | ------------------------------------------------------------- |
+| Outcome callbacks  | `onVerb` / past participle         | `onDeploy`, `onBuildRequired`, `onError`                      |
+| Boolean state      | `isX`                              | `busy` (exception, pre-dates rule), `isNotAuthenticatedError` |
+| Strategy injection | bare noun                          | `client`, `buildClient`, `validator`-style                    |
+| Analytics events   | `dropzone_snake_case` — **frozen** | `DROPZONE_EVENTS` (test-pinned wire names)                    |
+| Error predicates   | `isXError(err)`                    | `isNotAuthenticatedError`                                     |
+| Files              | filename = main export             | `detectBuild.ts`, `buildStash.ts`                             |
+
+### Comments
+
+- **WHY over WHAT.** A comment earns its place by stating something the code
+  can't: an invariant, an observed API behavior, a browser quirk, a
+  don't-simplify warning. Never narrate the next line.
+- **Record observed API behavior, with receipts.** The model comment in this
+  package: readiness polling keys off `deploy_id` (BSON), not `deploy.id` (site
+  UUID), "or the request 401s misleadingly" — naming the server-side file. Say
+  what the server _actually does_, and link the server source when you can.
+- **Repeat load-bearing quirk notes at every call site.** The `deploy_id` note
+  appears in the client _and_ the orchestrator on purpose — a note that only
+  exists where nobody is reading protects nothing.
+- **"Don't simplify" notes name what breaks** — the invariant, and ideally the
+  test that pins it (e.g. the `NotAuthenticatedError` boundary below).
+- **No `@param`/`@returns`.** Types carry the shape; JSDoc carries rationale
+  and edge cases. (react-dropzone: zero `@param` across its entire source.)
+- File-header purpose blocks only where the filename undersells the contents.
+
+### Errors
+
+- **Class per failure, each with a readonly kebab-case `code` brand.** This
+  package ships as raw TS (`./components`) _and_ compiled dist (`./preact`,
+  `./drop-core`) — two copies of a class can coexist in one app and defeat
+  `instanceof`. Detection that steers control flow must go through a
+  code-checking predicate (`isNotAuthenticatedError`), never bare `instanceof`.
+- **`NotAuthenticatedError` is pre-mutation only.** It may be thrown solely
+  before anything is created (token gate, site-create 401) — it is the signal
+  that an anonymous retry is safe. Throwing it after a site exists would strand
+  an empty project and deploy a duplicate. Pinned by tests.
+- **Humanized copy lives in `humanizeDropError`, in this package.** A
+  deliberate divergence from @vercel/client (which leaves rendering to the
+  CLI): our consumers render our copy directly, and the docs promise it.
+- Transient upload failures retry on `UPLOAD_RETRY_DELAYS_MS` (backoff as
+  data, the tus idiom); **400/422 never retry** — the request itself is wrong.
+
+### Considered and rejected
+
+- **Async-generator lifecycles** (@vercel/client): our phase-callback design is
+  equivalent and churn-free; `DeployPhase` is a closed union, which netlify-cli's
+  own author wished theirs was.
+- **Kebab-case event renames**: `dropzone_*` wire names are pinned analytics
+  history; `analytics.test.ts` fails on any rename. Append-only.
+- **`getRootProps`/`getInputProps` attribute getters** (react-dropzone, Uppy):
+  the right shape for a future framework-free UI tier shared with the app —
+  not something to bolt onto the shipped wrapper component.
+- **A `defaultOptions` object** (tus, Uppy): our destructured constructor
+  defaults are react-dropzone's pattern; either is fine, we have this one.

package/packages/drop-core/analytics.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { DROPZONE_EVENTS } from './analytics';
+
+describe('DROPZONE_EVENTS', () => {
+  it('pins the wire names — renaming one silently forks Amplitude/Segment history', () => {
+    expect(DROPZONE_EVENTS).toEqual({
+      FILES_DROPPED: 'dropzone_files_dropped',
+      BROWSE_OPENED: 'dropzone_browse_opened',
+      BUILD_REQUIRED: 'dropzone_build_required',
+      DEPLOY_SUCCEEDED: 'dropzone_deploy_succeeded',
+      BUILD_DEPLOY_SUCCEEDED: 'dropzone_build_deploy_succeeded',
+      DEPLOY_FAILED: 'dropzone_deploy_failed',
+      PROJECT_STASHED: 'dropzone_project_stashed',
+      RESUMED: 'dropzone_resumed',
+    });
+  });
+});

package/packages/drop-core/analytics.ts

@@ -0,0 +1,122 @@
+import type { 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.
+ */
+
+/** 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.
+ */
+export const DROPZONE_EVENTS = {
+  /** Files arrived via drag — the picker path reports its files on outcome events instead. */
+  FILES_DROPPED: 'dropzone_files_dropped',
+  /** The native file picker was opened (keyboard or click). */
+  BROWSE_OPENED: 'dropzone_browse_opened',
+  /** The drop needs a build — it will be built in place, stashed, or handed off. */
+  BUILD_REQUIRED: 'dropzone_build_required',
+  /** A static deploy went live (anonymous or into the visitor's account). */
+  DEPLOY_SUCCEEDED: 'dropzone_deploy_succeeded',
+  /** A build was enqueued in the visitor's account. */
+  BUILD_DEPLOY_SUCCEEDED: 'dropzone_build_deploy_succeeded',
+  /** Any attempt ended in an error (including a failed resume). */
+  DEPLOY_FAILED: 'dropzone_deploy_failed',
+  /** A logged-out build drop was stashed locally before the signup hand-off. */
+  PROJECT_STASHED: 'dropzone_project_stashed',
+  /** A stashed build drop was picked up for automatic deployment. */
+  RESUMED: 'dropzone_resumed',
+} as const;
+
+export type DropZoneEventName = (typeof DROPZONE_EVENTS)[keyof typeof DROPZONE_EVENTS];
+
+/** Properties the component adds to every event. */
+export interface DropZoneBaseEventProps {
+  /** Present when the consumer sets `analyticsId` — tells multiple zones apart. */
+  dropzone_id?: string;
+}
+
+export interface FilesDroppedProps extends DropZoneBaseEventProps {
+  method: 'drag';
+  file_count: number;
+  /** Omitted — never `[]` — when the browser exposes no files. */
+  file_types?: string[];
+}
+
+export interface BrowseOpenedProps extends DropZoneBaseEventProps {
+  method: 'keyboard' | 'click';
+}
+
+export interface BuildRequiredProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  reason: BuildReason | null;
+  file_count: number;
+  file_types?: string[];
+}
+
+export interface DeploySucceededProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  site_name: string;
+  file_count: number;
+  /** Whether the deploy landed directly in the visitor's account. */
+  authenticated: boolean;
+  /** Present only when an authenticated attempt bounced (stale login hint) and the drop completed anonymously. */
+  auth_fallback?: true;
+  file_types?: string[];
+}
+
+export interface BuildDeploySucceededProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  reason: BuildReason | null;
+  site_name: string;
+  file_count: number;
+  /** Present when build settings were synthesised into the archive. */
+  framework?: string;
+  file_types?: string[];
+}
+
+export interface DeployFailedProps extends DropZoneBaseEventProps {
+  /** Absent when the failure comes from a stash resume rather than a live drop gesture. */
+  method?: DropMethod;
+  /** Raw failure reason (e.g. "drop failed: 429", "resume_failed") — the humanized copy goes to the UI, not here. */
+  reason: string;
+  /** Present only when the file set is known (absent when reading itself threw). */
+  file_count?: number;
+  file_types?: string[];
+}
+
+export interface ProjectStashedProps extends DropZoneBaseEventProps {
+  method: DropMethod;
+  reason: BuildReason | null;
+  file_count: number;
+  file_types?: string[];
+}
+
+/** A resume starts from storage, not a fresh gesture — no method or file set to report. */
+export type ResumedProps = DropZoneBaseEventProps;
+
+/** Event name → its property shape, for typed emitters and sinks on either side of the seam. */
+export interface DropZoneEventProperties {
+  dropzone_files_dropped: FilesDroppedProps;
+  dropzone_browse_opened: BrowseOpenedProps;
+  dropzone_build_required: BuildRequiredProps;
+  dropzone_deploy_succeeded: DeploySucceededProps;
+  dropzone_build_deploy_succeeded: BuildDeploySucceededProps;
+  dropzone_deploy_failed: DeployFailedProps;
+  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.
+ */
+export type TrackFn = (event: string, properties?: Record<string, unknown>) => void;

package/packages/drop-core/authedApi.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSiteInAccount, pollDeployUntilSettled } from './authedApi';
+import { NotAuthenticatedError, SiteCreateError } from './errors';
+
+const PROXY = '/access-control/bb-api/api/v1';
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('createSiteInAccount', () => {
+  const record = () => {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    vi.stubGlobal('fetch', async (url: unknown, init: RequestInit = {}) => {
+      calls.push({ url: String(url), init });
+      return { ok: true, status: 200, json: async () => ({ id: 's', name: 'n' }) } as Response;
+    });
+    return calls;
+  };
+
+  it('POSTs through the proxy on the session cookie, attributed to drop', async () => {
+    const calls = record();
+    const site = await createSiteInAccount(PROXY);
+    expect(site).toEqual({ id: 's', name: 'n' });
+    expect(calls[0].url).toBe(`${PROXY}/sites`);
+    expect(calls[0].init.credentials).toBe('include');
+    expect(JSON.parse(String(calls[0].init.body))).toEqual({ created_via: 'drop' });
+  });
+
+  it('scopes to the account slug when given', async () => {
+    const calls = record();
+    await createSiteInAccount(PROXY, 'my-team');
+    expect(calls[0].url).toBe(`${PROXY}/my-team/sites`);
+  });
+
+  it.each([401, 403])(
+    'maps a %i — pre-mutation — to NotAuthenticatedError',
+    async (status: number) => {
+      vi.stubGlobal('fetch', async () => ({ ok: false, status, json: async () => ({}) }));
+      await expect(createSiteInAccount(PROXY)).rejects.toBeInstanceOf(NotAuthenticatedError);
+    }
+  );
+
+  it('wraps any other failure in SiteCreateError with the status', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 500, json: async () => ({}) }));
+    const failure = await createSiteInAccount(PROXY).catch(e => e);
+    expect(failure).toBeInstanceOf(SiteCreateError);
+    expect(failure.status).toBe(500);
+  });
+});
+
+describe('pollDeployUntilSettled', () => {
+  const poll = (states: Array<{ ok: boolean; state?: string; error_message?: string }>) => {
+    let call = 0;
+    const urls: string[] = [];
+    vi.stubGlobal('fetch', async (url: unknown, init: RequestInit = {}) => {
+      urls.push(String(url) + `|${init.credentials}`);
+      const next = states[Math.min(call++, states.length - 1)];
+      return { ok: next.ok, status: 200, json: async () => next } as Response;
+    });
+    return {
+      urls,
+      run: () =>
+        pollDeployUntilSettled({
+          proxyBase: PROXY,
+          deployId: 'd',
+          pollIntervalMs: 1,
+          timeoutMs: 5,
+        }),
+    };
+  };
+
+  it('reads the deploy through the proxy on the cookie until ready', async () => {
+    const { run, urls } = poll([
+      { ok: true, state: 'processing' },
+      { ok: true, state: 'ready' },
+    ]);
+    expect(await run()).toEqual({ outcome: 'ready' });
+    expect(urls[0]).toBe(`${PROXY}/deploys/d|include`);
+  });
+
+  it('reports terminal failures with the API error message', async () => {
+    const { run } = poll([{ ok: true, state: 'error', error_message: 'boom' }]);
+    expect(await run()).toEqual({ outcome: 'failed', errorMessage: 'boom' });
+  });
+
+  it('treats rejected as a failure too', async () => {
+    const { run } = poll([{ ok: true, state: 'rejected' }]);
+    expect(await run()).toEqual({ outcome: 'failed', errorMessage: undefined });
+  });
+
+  it('skips transient non-ok reads rather than failing the deploy', async () => {
+    const { run } = poll([{ ok: false }, { ok: true, state: 'ready' }]);
+    expect(await run()).toEqual({ outcome: 'ready' });
+  });
+
+  it('times out after timeoutMs / pollIntervalMs polls', async () => {
+    const { run, urls } = poll([{ ok: true, state: 'building' }]);
+    expect(await run()).toEqual({ outcome: 'timed-out' });
+    expect(urls).toHaveLength(5);
+  });
+});

package/packages/drop-core/authedApi.ts

@@ -0,0 +1,81 @@
+import type { BuildSite } from './types';
+import { NotAuthenticatedError, SiteCreateError } from './errors';
+
+/**
+ * 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.)
+ */
+
+/**
+ * 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.
+ */
+export async function createSiteInAccount(
+  proxyBase: string,
+  accountSlug?: string
+): Promise<BuildSite> {
+  const path = accountSlug ? `/${accountSlug}/sites` : '/sites';
+  const res = await fetch(`${proxyBase}${path}`, {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ created_via: 'drop' }),
+  });
+  if (res.status === 401 || res.status === 403) throw new NotAuthenticatedError();
+  if (!res.ok) throw new SiteCreateError(res.status);
+  return res.json();
+}
+
+/** How a watched deploy ended. `errorMessage` is the API's own explanation, when it gave one. */
+export type SettledDeploy =
+  { outcome: 'ready' } | { outcome: 'failed'; errorMessage?: string } | { outcome: 'timed-out' };
+
+/** Deploy states that end the wait — `ready` succeeds, the rest are failures. */
+const TERMINAL_STATES = new Set(['ready', 'error', 'rejected']);
+
+interface DeployState {
+  state?: string;
+  error_message?: string;
+}
+
+/**
+ * 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.
+ */
+export async function pollDeployUntilSettled(options: {
+  proxyBase: string;
+  deployId: string;
+  pollIntervalMs: number;
+  timeoutMs: number;
+}): Promise<SettledDeploy> {
+  const { proxyBase, deployId, pollIntervalMs, timeoutMs } = options;
+  const deadline = timeoutMs / pollIntervalMs;
+  for (let i = 0; i < deadline; i++) {
+    const res = await fetch(`${proxyBase}/deploys/${deployId}`, { credentials: 'include' });
+    if (res.ok) {
+      const deploy: DeployState = await res.json();
+      if (deploy.state && TERMINAL_STATES.has(deploy.state)) {
+        if (deploy.state === 'ready') return { outcome: 'ready' };
+        return { outcome: 'failed', errorMessage: deploy.error_message };
+      }
+    }
+    await new Promise(r => setTimeout(r, pollIntervalMs));
+  }
+  return { outcome: 'timed-out' };
+}

package/packages/drop-core/authedDropClient.test.ts

@@ -0,0 +1,196 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AuthenticatedDropClient } from './authedDropClient';
+import { NotAuthenticatedError } from './errors';
+
+const PROXY = '/access-control/bb-api/api/v1';
+const API = 'https://api.netlify.com/api/v1';
+
+interface RecordedCall {
+  url: string;
+  init: RequestInit;
+}
+
+/** Stub fetch that answers like the happy-path API and records every request. */
+function stubApi() {
+  const calls: RecordedCall[] = [];
+  vi.stubGlobal('fetch', async (url: unknown, init: RequestInit = {}) => {
+    calls.push({ url: String(url), init });
+    const u = String(url);
+    const body = u.endsWith('/sites')
+      ? { id: 'site-uuid', name: 'my-account-site' }
+      : u.endsWith('/deploys')
+        ? { id: 'deploy-bson', required: ['aaa'] }
+        : { state: 'ready' };
+    return { ok: true, status: 200, json: async () => body } as Response;
+  });
+  return calls;
+}
+
+const client = (getUploadToken = async (): Promise<string | null> => 'bearer-abc') =>
+  new AuthenticatedDropClient({ getUploadToken, pollIntervalMs: 1, timeoutMs: 5 });
+
+const content = new TextEncoder().encode('x').buffer as ArrayBuffer;
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('AuthenticatedDropClient transport', () => {
+  it('splits requests: JSON rides the cookie proxy, uploads go direct with the bearer', async () => {
+    const calls = stubApi();
+    const c = client();
+    const token = await c.getToken();
+    const deploy = await c.createDeploy({ '/index.html': 'aaa' }, token);
+    await c.uploadFile(deploy.deploy_id, '/index.html', content, token);
+    await c.waitUntilReady(deploy, token);
+
+    const [site, deployCreate, upload, poll] = calls;
+    expect(site.url).toBe(`${PROXY}/sites`);
+    expect(deployCreate.url).toBe(`${PROXY}/sites/site-uuid/deploys`);
+    // Readiness and file PUTs key off deploy_id (BSON), never the site UUID.
+    expect(upload.url).toBe(`${API}/deploys/deploy-bson/files/index.html`);
+    expect(poll.url).toBe(`${PROXY}/deploys/deploy-bson`);
+
+    for (const jsonCall of [site, deployCreate, poll]) {
+      expect(jsonCall.init.credentials).toBe('include');
+      expect((jsonCall.init.headers as Record<string, string>)?.Authorization).toBeUndefined();
+    }
+    expect((upload.init.headers as Record<string, string>).Authorization).toBe('Bearer bearer-abc');
+    expect(upload.init.credentials).toBeUndefined();
+  });
+
+  it('creates the site with created_via: drop and the deploy with the digest', async () => {
+    const calls = stubApi();
+    const c = client();
+    await c.createDeploy({ '/index.html': 'aaa' }, await c.getToken());
+    expect(JSON.parse(String(calls[0].init.body))).toEqual({ created_via: 'drop' });
+    expect(JSON.parse(String(calls[1].init.body))).toEqual({
+      files: { '/index.html': 'aaa' },
+      deploy_source: 'drop',
+    });
+  });
+
+  it('scopes site creation to the account slug when given', async () => {
+    const calls = stubApi();
+    const c = new AuthenticatedDropClient({
+      getUploadToken: async () => 'tok',
+      accountSlug: 'my-team',
+    });
+    await c.createDeploy({}, 'tok');
+    expect(calls[0].url).toBe(`${PROXY}/my-team/sites`);
+  });
+
+  it('maps the site + deploy responses into the anonymous DropResponse shape', async () => {
+    stubApi();
+    const c = client();
+    const deploy = await c.createDeploy({ '/index.html': 'aaa' }, 'tok');
+    expect(deploy).toEqual({
+      id: 'site-uuid',
+      deploy_id: 'deploy-bson',
+      subdomain: 'my-account-site',
+      required: ['aaa'],
+    });
+  });
+});
+
+describe('AuthenticatedDropClient upload-token lifecycle', () => {
+  it('reuses the gate-minted token inside the reuse window', async () => {
+    stubApi();
+    let minted = 0;
+    const c = client(async () => `tok-${++minted}`);
+    const token = await c.getToken();
+    await c.uploadFile('d', '/a', content, token);
+    await c.uploadFile('d', '/b', content, token);
+    expect(minted).toBe(1);
+  });
+
+  it('re-mints once the cached token nears the server-side 30s expiry', async () => {
+    stubApi();
+    let minted = 0;
+    let now = 1_000_000;
+    vi.spyOn(Date, 'now').mockImplementation(() => now);
+
+    const c = client(async () => `tok-${++minted}`);
+    const token = await c.getToken();
+    await c.uploadFile('d', '/a', content, token);
+    expect(minted).toBe(1);
+
+    now += 21_000; // past TOKEN_REUSE_MS (20s)
+    await c.uploadFile('d', '/b', content, token);
+    expect(minted).toBe(2);
+
+    await c.uploadFile('d', '/c', content, token);
+    expect(minted).toBe(2); // the renewed token is reused in turn
+  });
+});
+
+describe('AuthenticatedDropClient auth boundaries', () => {
+  it('throws NotAuthenticatedError at the gate when no token can be minted', async () => {
+    await expect(client(async () => null).getToken()).rejects.toBeInstanceOf(NotAuthenticatedError);
+  });
+
+  it('throws NotAuthenticatedError when site creation is refused — pre-mutation, fallback-safe', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 401, json: async () => ({}) }));
+    await expect(client().createDeploy({}, 'tok')).rejects.toBeInstanceOf(NotAuthenticatedError);
+  });
+
+  it('throws a plain Error — never NotAuthenticatedError — when minting fails mid-upload', async () => {
+    // The anti-duplicate invariant: by upload time the site exists, and a
+    // NotAuthenticatedError would send the drop back through the anonymous
+    // path, stranding an empty project and deploying twice.
+    stubApi();
+    let minted = 0;
+    let now = 1_000_000;
+    vi.spyOn(Date, 'now').mockImplementation(() => now);
+    const c = client(async () => (++minted === 1 ? 'tok' : null));
+    const token = await c.getToken();
+    now += 60_000;
+    const failure = await c.uploadFile('d', '/a', content, token).catch(e => e);
+    expect(failure).toBeInstanceOf(Error);
+    expect(failure).not.toBeInstanceOf(NotAuthenticatedError);
+  });
+
+  it('surfaces upload HTTP failures with the status attached', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 413, json: async () => ({}) }));
+    const c = client();
+    const failure = await c.uploadFile('d', '/big', content, 'tok').catch(e => e);
+    expect(failure.status).toBe(413);
+  });
+});
+
+describe('AuthenticatedDropClient polling', () => {
+  const pollClient = (states: Array<{ ok: boolean; state?: string; error_message?: string }>) => {
+    let call = 0;
+    vi.stubGlobal('fetch', async () => {
+      const next = states[Math.min(call++, states.length - 1)];
+      return { ok: next.ok, status: next.ok ? 200 : 500, json: async () => next } as Response;
+    });
+    return client();
+  };
+
+  it('resolves when the deploy goes ready, skipping transient bad reads', async () => {
+    const c = pollClient([
+      { ok: false },
+      { ok: true, state: 'processing' },
+      { ok: true, state: 'ready' },
+    ]);
+    await expect(
+      c.waitUntilReady({ id: 's', deploy_id: 'd', subdomain: 'x', required: [] }, 'tok')
+    ).resolves.toBeUndefined();
+  });
+
+  it('fails with the deploy error message on a terminal error state', async () => {
+    const c = pollClient([{ ok: true, state: 'error', error_message: 'no index.html' }]);
+    await expect(
+      c.waitUntilReady({ id: 's', deploy_id: 'd', subdomain: 'x', required: [] }, 'tok')
+    ).rejects.toThrow('deploy failed: no index.html');
+  });
+
+  it('times out with the shared humanizable message', async () => {
+    const c = pollClient([{ ok: true, state: 'uploading' }]);
+    await expect(
+      c.waitUntilReady({ id: 's', deploy_id: 'd', subdomain: 'x', required: [] }, 'tok')
+    ).rejects.toThrow('Deploy did not become ready in time');
+  });
+});