@netlify/spark-ui 1.31.0-alpha.2 → 1.31.0-alpha.4

package/packages/drop-core/authedDropClient.ts

@@ -0,0 +1,210 @@
+import {
+  createSiteInAccount,
+  DEFAULT_API_BASE,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_PROXY_BASE,
+  DEFAULT_TIMEOUT_MS,
+  pollDeployUntilSettled,
+} from './authedApi';
+import { apiError, type DropClient } from './client';
+import { NotAuthenticatedError } from './errors';
+import type { BuildSite, 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).
+   */
+  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).
+   */
+  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.
+   */
+  getUploadToken: () => Promise<string | null>;
+  /** Create the site in this account. Omit to use the user's default account. */
+  accountSlug?: string;
+  /** How often to re-read the deploy while waiting. Default 1s. */
+  pollIntervalMs?: number;
+  /** How long to wait before giving up on the deploy. Default 10 minutes. */
+  timeoutMs?: number;
+}
+
+/**
+ * How long a minted upload token is reused before minting another. The server
+ * issues non-app origins a 30s token, so this leaves a margin for the request
+ * it authorizes to finish.
+ */
+const TOKEN_REUSE_MS = 20 * 1000;
+
+/** Response body of `POST /sites/{id}/deploys` — the slice the drop flow needs. */
+interface SiteDeployResponse {
+  /** deploy id (BSON) */
+  id: string;
+  /** SHAs the backend does NOT yet have — only these get uploaded */
+  required?: string[];
+}
+
+/**
+ * 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.
+ */
+export class AuthenticatedDropClient implements DropClient {
+  private proxyBase: string;
+  private apiBase: string;
+  private getUploadToken: () => Promise<string | null>;
+  private accountSlug?: string;
+  private pollIntervalMs: number;
+  private timeoutMs: number;
+  private cachedToken?: { value: string; mintedAt: number };
+
+  constructor({
+    proxyBase = DEFAULT_PROXY_BASE,
+    apiBase = DEFAULT_API_BASE,
+    getUploadToken,
+    accountSlug,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  }: AuthenticatedDropClientConfig) {
+    this.proxyBase = proxyBase;
+    this.apiBase = apiBase;
+    this.getUploadToken = getUploadToken;
+    this.accountSlug = accountSlug;
+    this.pollIntervalMs = pollIntervalMs;
+    this.timeoutMs = timeoutMs;
+  }
+
+  /**
+   * The auth gate. Minting here — before anything is created — is what lets a
+   * logged-out visitor fail cleanly and fall back to the anonymous flow. The
+   * returned token is threaded through `deployFiles`, but only the uploads
+   * actually need one, and they re-mint rather than trusting this to still be
+   * valid by the time they run.
+   */
+  async getToken(): Promise<string> {
+    const token = await this.getUploadToken();
+    if (!token) throw new NotAuthenticatedError();
+    this.cachedToken = { value: token, mintedAt: Date.now() };
+    return token;
+  }
+
+  /**
+   * A token young enough to authorize an upload, minting a new one once the
+   * cached one nears its 30s expiry.
+   *
+   * Deliberately NOT `NotAuthenticatedError` when minting fails: by the time
+   * uploads run the site already exists, and that error would send the drop
+   * back through the anonymous path — leaving an empty project behind and
+   * deploying a duplicate. See the class doc.
+   */
+  private async freshToken(): Promise<string> {
+    const now = Date.now();
+    if (this.cachedToken && now - this.cachedToken.mintedAt < TOKEN_REUSE_MS) {
+      return this.cachedToken.value;
+    }
+    const value = await this.getUploadToken();
+    if (!value) throw new Error('could not renew the upload token');
+    this.cachedToken = { value, mintedAt: now };
+    return value;
+  }
+
+  /**
+   * 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.
+   */
+  async createDeploy(files: Digest, _token: string): Promise<DropResponse> {
+    // A logged-out visitor fails inside createSiteInAccount, before anything is
+    // created — the one point an anonymous fallback is still safe (class doc).
+    const site: BuildSite = await createSiteInAccount(this.proxyBase, this.accountSlug);
+
+    const deployRes = await fetch(`${this.proxyBase}/sites/${site.id}/deploys`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ files, deploy_source: 'drop' }),
+    });
+    if (!deployRes.ok) throw apiError('deploy create', deployRes.status);
+    const deploy: SiteDeployResponse = await deployRes.json();
+
+    return {
+      id: site.id,
+      deploy_id: deploy.id,
+      subdomain: site.name,
+      required: deploy.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.
+   */
+  async uploadFile(
+    deployId: string,
+    path: string,
+    content: ArrayBuffer,
+    _token: string
+  ): Promise<void> {
+    const token = await this.freshToken();
+    const res = await fetch(`${this.apiBase}/deploys/${deployId}/files${path}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/octet-stream', Authorization: `Bearer ${token}` },
+      body: content,
+    });
+    if (!res.ok) throw apiError(`upload ${path}`, res.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.
+   */
+  async waitUntilReady(deploy: DropResponse, _token: string): Promise<void> {
+    const settled = await pollDeployUntilSettled({
+      proxyBase: this.proxyBase,
+      deployId: deploy.deploy_id,
+      pollIntervalMs: this.pollIntervalMs,
+      timeoutMs: this.timeoutMs,
+    });
+    if (settled.outcome === 'ready') return;
+    // Plain errors on purpose: humanizeDropError maps them, and nothing here
+    // may look like NotAuthenticatedError once the site exists (class doc).
+    if (settled.outcome === 'failed') {
+      throw new Error(
+        settled.errorMessage ? `deploy failed: ${settled.errorMessage}` : 'deploy failed'
+      );
+    }
+    // Same message the anonymous client uses, so humanizeDropError maps it.
+    throw new Error('Deploy did not become ready in time');
+  }
+}

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

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AuthenticatedBuildClient } from './buildClient';
+import {
+  BuildCreateError,
+  BuildFailedError,
+  BuildTimeoutError,
+  NotAuthenticatedError,
+} from './errors';
+
+const PROXY = '/access-control/bb-api/api/v1';
+const API = 'https://api.netlify.com/api/v1';
+
+const zip = new File(['zip-bytes'], 'source.zip', { type: 'application/zip' });
+
+const client = (getUploadToken = async (): Promise<string | null> => 'bearer-abc') =>
+  new AuthenticatedBuildClient({ getUploadToken, pollIntervalMs: 1, timeoutMs: 5 });
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('AuthenticatedBuildClient.createSite', () => {
+  it('creates the site through the cookie proxy with created_via: drop', async () => {
+    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;
+    });
+    await client().createSite();
+    expect(calls[0].url).toBe(`${PROXY}/sites`);
+    expect(calls[0].init.credentials).toBe('include');
+    expect((calls[0].init.headers as Record<string, string>).Authorization).toBeUndefined();
+    expect(JSON.parse(String(calls[0].init.body))).toEqual({ created_via: 'drop' });
+  });
+
+  it('throws NotAuthenticatedError on 401 — before anything is created', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 401, json: async () => ({}) }));
+    await expect(client().createSite()).rejects.toBeInstanceOf(NotAuthenticatedError);
+  });
+});
+
+describe('AuthenticatedBuildClient.createBuildFromZip', () => {
+  it('uploads the archive direct to api.netlify.com as multipart with a fresh bearer', async () => {
+    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: 'b', deploy_id: 'd' }) } as Response;
+    });
+    const build = await client().createBuildFromZip('site-id', zip);
+    expect(build).toEqual({ id: 'b', deploy_id: 'd' });
+    const [call] = calls;
+    expect(call.url).toBe(`${API}/sites/site-id/builds`);
+    expect((call.init.headers as Record<string, string>).Authorization).toBe('Bearer bearer-abc');
+    // No explicit Content-Type: the browser must add the multipart boundary itself.
+    expect((call.init.headers as Record<string, string>)['Content-Type']).toBeUndefined();
+    const body = call.init.body as FormData;
+    expect(body.get('zip')).toBeInstanceOf(File);
+    expect(body.get('title')).toBe('Build from drop deployment');
+  });
+
+  it('throws NotAuthenticatedError when no upload token can be minted', async () => {
+    await expect(client(async () => null).createBuildFromZip('s', zip)).rejects.toBeInstanceOf(
+      NotAuthenticatedError
+    );
+  });
+
+  it('wraps other upload failures in BuildCreateError with the status', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 413, json: async () => ({}) }));
+    const failure = await client()
+      .createBuildFromZip('s', zip)
+      .catch(e => e);
+    expect(failure).toBeInstanceOf(BuildCreateError);
+    expect(failure.status).toBe(413);
+  });
+});
+
+describe('AuthenticatedBuildClient.waitUntilBuildReady', () => {
+  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: 200, json: async () => next } as Response;
+    });
+    return client();
+  };
+
+  it('has nothing to poll before the API assigns a deploy id', async () => {
+    vi.stubGlobal('fetch', vi.fn());
+    await client().waitUntilBuildReady({ id: 'b' });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('polls the deploy through the proxy until ready', async () => {
+    const c = pollClient([
+      { ok: true, state: 'building' },
+      { ok: true, state: 'ready' },
+    ]);
+    await expect(c.waitUntilBuildReady({ id: 'b', deploy_id: 'd' })).resolves.toBeUndefined();
+  });
+
+  it('surfaces the build error message via BuildFailedError', async () => {
+    const c = pollClient([{ ok: true, state: 'error', error_message: 'Command failed' }]);
+    const failure = await c.waitUntilBuildReady({ id: 'b', deploy_id: 'd' }).catch(e => e);
+    expect(failure).toBeInstanceOf(BuildFailedError);
+    expect(failure.reason).toBe('Command failed');
+  });
+
+  it('gives up with BuildTimeoutError when the build never settles', async () => {
+    const c = pollClient([{ ok: true, state: 'building' }]);
+    await expect(c.waitUntilBuildReady({ id: 'b', deploy_id: 'd' })).rejects.toBeInstanceOf(
+      BuildTimeoutError
+    );
+  });
+});

package/packages/{components/preact/DropZone/drop-core → drop-core}/buildClient.ts

@@ -1,21 +1,20 @@
+import {
+  createSiteInAccount,
+  DEFAULT_API_BASE,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_PROXY_BASE,
+  DEFAULT_TIMEOUT_MS,
+  pollDeployUntilSettled,
+} from './authedApi';
 import {
   BuildCreateError,
   BuildFailedError,
   BuildTimeoutError,
   NotAuthenticatedError,
-  SiteCreateError,
 } from './errors';
+import type { BuildSite } from './types';
 
-/** The subset of a Netlify Site the drop flow needs to redirect and report. */
-export interface BuildSite {
-  /** site id (UUID) */
-  id: string;
-  /** the *.netlify.app subdomain, also the app's URL segment */
-  name: string;
-  /** https://<name>.netlify.app */
-  ssl_url?: string;
-  url?: string;
-}
+export type { BuildSite } from './types';
 
 /** The subset of a Netlify Build returned by `POST /sites/{id}/builds`. */
 export interface BuildResponse {
@@ -33,20 +32,27 @@ export interface BuildClient {
 
 export interface AuthenticatedBuildClientConfig {
   /**
-   * API base for every call. Requests go straight to `api.netlify.com`, whose
-   * `/api/*` CORS policy allows any origin, rather than through a consumer's
-   * access-control rewrite — that proxy allowlists paths per origin, and site
-   * creation and deploy reads are not on the list for netlify.com (they 400
-   * with `x-debug: request origin not allowed to call endpoint`). The zip
-   * upload could not use that proxy regardless: it runs in a Lambda with a
-   * ~6MB request body limit.
+   * 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).
+   */
+  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).
    */
   apiBase?: string;
   /**
-   * Mint a short-lived bearer token authorizing the calls. On netlify.com this
-   * is `GET /access-control/generate-access-control-token`, whose
+   * 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`.
    */
   getUploadToken: () => Promise<string | null>;
   /** Create the site in this account. Omit to use the user's default account. */
@@ -59,18 +65,6 @@ export interface AuthenticatedBuildClientConfig {
   timeoutMs?: number;
 }
 
-const API_BASE = 'https://api.netlify.com/api/v1';
-const POLL_INTERVAL_MS = 1000;
-const TIMEOUT_MS = 10 * 60 * 1000;
-
-/** 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;
-}
-
 /**
  * Authenticated drop client for projects that need a build. Unlike
  * `AnonymousDropClient` — which creates an account-less static site and can only
@@ -84,6 +78,7 @@ interface DeployState {
  * short-lived bearer token because the proxy can't carry a body that large.
  */
 export class AuthenticatedBuildClient implements BuildClient {
+  private proxyBase: string;
   private apiBase: string;
   private getUploadToken: () => Promise<string | null>;
   private accountSlug?: string;
@@ -92,13 +87,15 @@ export class AuthenticatedBuildClient implements BuildClient {
   private timeoutMs: number;
 
   constructor({
-    apiBase = API_BASE,
+    proxyBase = DEFAULT_PROXY_BASE,
+    apiBase = DEFAULT_API_BASE,
     getUploadToken,
     accountSlug,
     title = 'Build from drop deployment',
-    pollIntervalMs = POLL_INTERVAL_MS,
-    timeoutMs = TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
   }: AuthenticatedBuildClientConfig) {
+    this.proxyBase = proxyBase;
     this.apiBase = apiBase;
     this.getUploadToken = getUploadToken;
     this.accountSlug = accountSlug;
@@ -108,24 +105,12 @@ export class AuthenticatedBuildClient implements BuildClient {
   }
 
   /**
-   * Create the site the build deploys into. Authorized by the bearer token;
-   * without an account slug the API picks the user's default account.
+   * 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.
    */
   async createSite(): Promise<BuildSite> {
-    const token = await this.getUploadToken();
-    if (!token) throw new NotAuthenticatedError();
-
-    const path = this.accountSlug ? `/${this.accountSlug}/sites` : '/sites';
-    const res = await fetch(`${this.apiBase}${path}`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
-      body: JSON.stringify({ created_via: 'drop' }),
-    });
-    // A logged-out visitor gets a 401 here rather than at the token step, since
-    // this is the first call that needs the session.
-    if (res.status === 401 || res.status === 403) throw new NotAuthenticatedError();
-    if (!res.ok) throw new SiteCreateError(res.status);
-    return res.json();
+    return createSiteInAccount(this.proxyBase, this.accountSlug);
   }
 
   /**
@@ -133,6 +118,11 @@ export class AuthenticatedBuildClient implements BuildClient {
    * (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.
+   *
+   * 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.
    */
   async createBuildFromZip(siteId: string, zip: File): Promise<BuildResponse> {
     const token = await this.getUploadToken();
@@ -159,29 +149,24 @@ export class AuthenticatedBuildClient implements BuildClient {
    * 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, which
-   * can outlive the bearer token minted for it. Each poll re-mints so a long
-   * build keeps reading; a token that can't be minted any more ends the wait as
-   * a timeout rather than a false failure.
+   * 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.
    */
   async waitUntilBuildReady(build: BuildResponse): Promise<void> {
     if (!build.deploy_id) return;
 
-    const deadline = this.timeoutMs / this.pollIntervalMs;
-    for (let i = 0; i < deadline; i++) {
-      const token = await this.getUploadToken();
-      const res = await fetch(`${this.apiBase}/deploys/${build.deploy_id}`, {
-        headers: token ? { Authorization: `Bearer ${token}` } : {},
-      });
-      if (res.ok) {
-        const deploy: DeployState = await res.json();
-        if (deploy.state && TERMINAL_STATES.has(deploy.state)) {
-          if (deploy.state === 'ready') return;
-          throw new BuildFailedError(deploy.error_message);
-        }
-      }
-      await new Promise(r => setTimeout(r, this.pollIntervalMs));
-    }
+    const settled = await pollDeployUntilSettled({
+      proxyBase: this.proxyBase,
+      deployId: build.deploy_id,
+      pollIntervalMs: this.pollIntervalMs,
+      timeoutMs: this.timeoutMs,
+    });
+    if (settled.outcome === 'ready') return;
+    // The build's own error message is the only actionable part of a failure,
+    // so it travels on the typed error rather than being flattened away.
+    if (settled.outcome === 'failed') throw new BuildFailedError(settled.errorMessage);
     throw new BuildTimeoutError();
   }
 }

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

@@ -0,0 +1,85 @@
+import 'fake-indexeddb/auto';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { clearDropStash, hasDropStashMarker, loadDropStash, saveDropStash } from './buildStash';
+
+// Node environment on purpose: fake-indexeddb structured-clones Node's own
+// File/Blob faithfully, where a DOM shim's File comes back as a husk. The two
+// browser globals the module needs are stubbed below.
+const localStorageStub = () => {
+  const store = new Map<string, string>();
+  return {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => void store.set(k, v),
+    removeItem: (k: string) => void store.delete(k),
+  };
+};
+
+const stubQuota = (free: number) =>
+  vi.stubGlobal('navigator', { storage: { estimate: async () => ({ quota: free, usage: 0 }) } });
+
+const zip = () => new File(['zip-bytes'], 'source.zip', { type: 'application/zip' });
+
+beforeEach(async () => {
+  vi.stubGlobal('localStorage', localStorageStub());
+  stubQuota(10_000_000);
+  await clearDropStash();
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('buildStash', () => {
+  it('round-trips a drop: archive, settings, and the cheap marker', async () => {
+    const settings = { command: 'npm run build', publish: 'dist', framework: 'astro' };
+    expect(hasDropStashMarker()).toBe(false);
+
+    expect(await saveDropStash(zip(), settings)).toBe(true);
+    expect(hasDropStashMarker()).toBe(true);
+
+    const stash = await loadDropStash();
+    expect(stash?.buildSettings).toEqual(settings);
+    // A real, named File comes back out — rehydrated when the structured-clone
+    // implementation drops File identity.
+    expect(stash?.zipFile).toBeInstanceOf(File);
+    expect(stash?.zipFile.name).toBe('source.zip');
+    expect(await stash?.zipFile.text()).toBe('zip-bytes');
+  });
+
+  it('clears the stash and marker idempotently', async () => {
+    await saveDropStash(zip());
+    await clearDropStash();
+    expect(hasDropStashMarker()).toBe(false);
+    expect(await loadDropStash()).toBeNull();
+    await expect(clearDropStash()).resolves.toBeUndefined(); // second clear is a no-op
+  });
+
+  it('expires the stash after its TTL and cleans up on read', async () => {
+    await saveDropStash(zip());
+    const realNow = Date.now;
+    vi.spyOn(Date, 'now').mockImplementation(() => realNow() + 25 * 60 * 60 * 1000);
+    expect(await loadDropStash()).toBeNull();
+    expect(hasDropStashMarker()).toBe(false); // the marker carries its own expiry
+  });
+
+  it('declines to stash without comfortable quota headroom', async () => {
+    stubQuota(10); // nowhere near 2x the zip
+    expect(await saveDropStash(zip())).toBe(false);
+    expect(hasDropStashMarker()).toBe(false);
+  });
+
+  it('declines oversized archives outright', async () => {
+    const huge = { size: 201 * 1024 * 1024 } as File;
+    expect(await saveDropStash(huge)).toBe(false);
+  });
+
+  it('degrades to false/null when IndexedDB is missing, never throwing', async () => {
+    const original = globalThis.indexedDB;
+    vi.stubGlobal('indexedDB', undefined);
+    expect(await saveDropStash(zip())).toBe(false);
+    expect(await loadDropStash()).toBeNull();
+    await expect(clearDropStash()).resolves.toBeUndefined();
+    vi.stubGlobal('indexedDB', original);
+  });
+});