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

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

@@ -1,7 +1,14 @@
+import { createSiteInAccount, pollDeployUntilSettled } from './authedApi';
+import {
+  DEFAULT_API_BASE,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_PROXY_BASE,
+  DEFAULT_TIMEOUT_MS,
+  TOKEN_REUSE_MS,
+} from './constants';
 import { apiError, type DropClient } from './client';
-import type { BuildSite } from './buildClient';
-import type { Digest, DropResponse } from './types';
-import { NotAuthenticatedError, SiteCreateError } from './errors';
+import { DeployFailedError, DeployTimeoutError, NotAuthenticatedError } from './errors';
+import type { BuildSite, Digest, DropResponse } from './types';
 
 export interface AuthenticatedDropClientConfig {
   /**
@@ -35,30 +42,6 @@ export interface AuthenticatedDropClientConfig {
   timeoutMs?: number;
 }
 
-// Same defaults as AuthenticatedBuildClient — the ~15 lines shared with it
-// (constants + site create) are deliberately duplicated rather than extracted,
-// to avoid churn on the in-review build-client branch. Worth unifying once both
-// have landed.
-const PROXY_BASE = '/access-control/bb-api/api/v1';
-const API_BASE = 'https://api.netlify.com/api/v1';
-const POLL_INTERVAL_MS = 1000;
-const TIMEOUT_MS = 10 * 60 * 1000;
-
-/**
- * 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;
-
-/** 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;
-}
-
 /** Response body of `POST /sites/{id}/deploys` — the slice the drop flow needs. */
 interface SiteDeployResponse {
   /** deploy id (BSON) */
@@ -98,12 +81,12 @@ export class AuthenticatedDropClient implements DropClient {
   private cachedToken?: { value: string; mintedAt: number };
 
   constructor({
-    proxyBase = PROXY_BASE,
-    apiBase = API_BASE,
+    proxyBase = DEFAULT_PROXY_BASE,
+    apiBase = DEFAULT_API_BASE,
     getUploadToken,
     accountSlug,
-    pollIntervalMs = POLL_INTERVAL_MS,
-    timeoutMs = TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
   }: AuthenticatedDropClientConfig) {
     this.proxyBase = proxyBase;
     this.apiBase = apiBase;
@@ -114,11 +97,8 @@ export class AuthenticatedDropClient implements DropClient {
   }
 
   /**
-   * 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.
+   * 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.
    */
   async getToken(): Promise<string> {
     const token = await this.getUploadToken();
@@ -129,12 +109,8 @@ export class AuthenticatedDropClient implements DropClient {
 
   /**
    * 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.
+   * cached one nears its 30s expiry. A mint failure here is a plain `Error`,
+   * never `NotAuthenticatedError` — the site exists by now (class doc).
    */
   private async freshToken(): Promise<string> {
     const now = Date.now();
@@ -153,18 +129,7 @@ export class AuthenticatedDropClient implements DropClient {
    * `deployFiles` runs unchanged over either client.
    */
   async createDeploy(files: Digest, _token: string): Promise<DropResponse> {
-    const path = this.accountSlug ? `/${this.accountSlug}/sites` : '/sites';
-    const siteRes = await fetch(`${this.proxyBase}${path}`, {
-      method: 'POST',
-      credentials: 'include',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ created_via: 'drop' }),
-    });
-    // A logged-out visitor 401s here, before anything is created — the one
-    // point an anonymous fallback is still safe (see the class doc).
-    if (siteRes.status === 401 || siteRes.status === 403) throw new NotAuthenticatedError();
-    if (!siteRes.ok) throw new SiteCreateError(siteRes.status);
-    const site: BuildSite = await siteRes.json();
+    const site: BuildSite = await createSiteInAccount(this.proxyBase, this.accountSlug);
 
     const deployRes = await fetch(`${this.proxyBase}/sites/${site.id}/deploys`, {
       method: 'POST',
@@ -209,23 +174,16 @@ export class AuthenticatedDropClient implements DropClient {
    * than a bearer, so a deploy taking minutes can't outlive its own credentials.
    */
   async waitUntilReady(deploy: DropResponse, _token: string): Promise<void> {
-    const deadline = this.timeoutMs / this.pollIntervalMs;
-    for (let i = 0; i < deadline; i++) {
-      const res = await fetch(`${this.proxyBase}/deploys/${deploy.deploy_id}`, {
-        credentials: 'include',
-      });
-      if (res.ok) {
-        const state: DeployState = await res.json();
-        if (state.state && TERMINAL_STATES.has(state.state)) {
-          if (state.state === 'ready') return;
-          throw new Error(
-            state.error_message ? `deploy failed: ${state.error_message}` : 'deploy failed'
-          );
-        }
-      }
-      await new Promise(r => setTimeout(r, this.pollIntervalMs));
-    }
-    // Same message the anonymous client uses, so humanizeDropError maps it.
-    throw new Error('Deploy did not become ready in time');
+    const settled = await pollDeployUntilSettled({
+      proxyBase: this.proxyBase,
+      deployId: deploy.deploy_id,
+      pollIntervalMs: this.pollIntervalMs,
+      timeoutMs: this.timeoutMs,
+    });
+    if (settled.outcome === 'ready') return;
+    // Neither class is NotAuthenticatedError-shaped on purpose: once the site
+    // exists, nothing here may trigger the anonymous fallback (class doc).
+    if (settled.outcome === 'failed') throw new DeployFailedError(settled.errorMessage);
+    throw new DeployTimeoutError();
   }
 }

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,19 @@
+import { createSiteInAccount, pollDeployUntilSettled } from './authedApi';
+import {
+  DEFAULT_API_BASE,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_PROXY_BASE,
+  DEFAULT_TIMEOUT_MS,
+} from './constants';
 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 {
@@ -66,19 +64,6 @@ export interface AuthenticatedBuildClientConfig {
   timeoutMs?: number;
 }
 
-const PROXY_BASE = '/access-control/bb-api/api/v1';
-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
@@ -101,13 +86,13 @@ export class AuthenticatedBuildClient implements BuildClient {
   private timeoutMs: number;
 
   constructor({
-    proxyBase = PROXY_BASE,
-    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;
@@ -119,23 +104,12 @@ export class AuthenticatedBuildClient implements BuildClient {
   }
 
   /**
-   * Create the site the build deploys into. Goes through the proxy with
-   * `credentials: 'include'` so the app session authorizes it; 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 path = this.accountSlug ? `/${this.accountSlug}/sites` : '/sites';
-    const res = await fetch(`${this.proxyBase}${path}`, {
-      method: 'POST',
-      credentials: 'include',
-      headers: { 'Content-Type': 'application/json' },
-      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);
   }
 
   /**
@@ -182,20 +156,16 @@ export class AuthenticatedBuildClient implements BuildClient {
   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 res = await fetch(`${this.proxyBase}/deploys/${build.deploy_id}`, {
-        credentials: 'include',
-      });
-      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);
+  });
+});

package/packages/drop-core/buildStash.ts

@@ -0,0 +1,185 @@
+import type { InferredBuildSettings } from './detectBuild';
+
+/**
+ * Carry a build-required drop across the signup round-trip.
+ *
+ * A logged-out visitor's drop can't be built (builds have no anonymous
+ * equivalent), so before handing them to signup the zone stashes the source
+ * archive here — IndexedDB, because the zip is far beyond localStorage's
+ * budget. When they return to this origin authenticated, the zone deploys the
+ * stash automatically instead of asking them to drop again.
+ *
+ * Storage is per-origin: a stash written on www.netlify.com can only ever be
+ * resumed on www.netlify.com. That is the design, not a limitation — it is
+ * exactly why the hand-off page must bring the visitor back here.
+ *
+ * Every operation is failure-swallowing: the stash is an enhancement, and a
+ * browser without IndexedDB (or with a full quota) degrades to the plain
+ * signup redirect the zone always supported.
+ */
+
+export interface DropBuildStash {
+  /** The `source.zip` exactly as it would have been uploaded. */
+  zipFile: File;
+  /** Settings synthesised into the archive's netlify.toml, if any. */
+  buildSettings: InferredBuildSettings | null;
+  createdAt: number;
+}
+
+const DB_NAME = 'netlify-drop';
+const DB_VERSION = 1;
+const STORE_NAME = 'build-stash';
+const STASH_KEY = 'latest';
+const MARKER_KEY = 'dropBuildStash';
+const STASH_TTL_MS = 24 * 60 * 60 * 1000;
+const OPERATION_TIMEOUT_MS = 3000;
+const MAX_ZIP_BYTES = 200 * 1024 * 1024;
+/** Only stash when the quota comfortably fits the zip — never wedge the origin's storage. */
+const QUOTA_HEADROOM = 2;
+
+const withTimeout = <T>(promise: Promise<T>): Promise<T> =>
+  Promise.race([
+    promise,
+    new Promise<never>((_resolve, reject) => {
+      setTimeout(() => reject(new Error('IndexedDB operation timed out')), OPERATION_TIMEOUT_MS);
+    }),
+  ]);
+
+const openDatabase = (): Promise<IDBDatabase> =>
+  new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(STORE_NAME);
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+
+// One request per transaction; awaiting mid-transaction would auto-commit it.
+const runStoreOperation = <T>(
+  mode: IDBTransactionMode,
+  makeRequest: (store: IDBObjectStore) => IDBRequest<T>
+): Promise<T> =>
+  withTimeout(
+    openDatabase().then(
+      db =>
+        new Promise<T>((resolve, reject) => {
+          const request = makeRequest(db.transaction(STORE_NAME, mode).objectStore(STORE_NAME));
+          request.onsuccess = () => {
+            db.close();
+            resolve(request.result);
+          };
+          request.onerror = () => {
+            db.close();
+            reject(request.error);
+          };
+        })
+    )
+  );
+
+const hasEnoughQuota = async (bytes: number): Promise<boolean> => {
+  const { quota, usage } = await navigator.storage.estimate();
+  return quota !== undefined && usage !== undefined && quota - usage > bytes * QUOTA_HEADROOM;
+};
+
+// The marker is a plain localStorage flag with its own expiry, so page loads can
+// ask "is there anything to resume?" synchronously without opening IndexedDB.
+const setMarker = () => {
+  localStorage.setItem(MARKER_KEY, JSON.stringify({ expiresAt: Date.now() + STASH_TTL_MS }));
+};
+
+const clearMarker = () => {
+  localStorage.removeItem(MARKER_KEY);
+};
+
+/**
+ * Stash a drop's source archive for an automatic deploy after signup. Returns
+ * whether it was actually stored — callers use that only to phrase the
+ * hand-off, never to block it.
+ */
+export async function saveDropStash(
+  zipFile: File,
+  buildSettings: InferredBuildSettings | null = null
+): Promise<boolean> {
+  try {
+    if (
+      typeof indexedDB === 'undefined' ||
+      !navigator.storage?.estimate ||
+      zipFile.size > MAX_ZIP_BYTES ||
+      !(await hasEnoughQuota(zipFile.size))
+    ) {
+      return false;
+    }
+    const record: DropBuildStash = { zipFile, buildSettings, createdAt: Date.now() };
+    await runStoreOperation('readwrite', store => store.put(record, STASH_KEY));
+    setMarker();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The stashed drop, or null when there is none, it expired, or storage is unavailable. */
+export async function loadDropStash(): Promise<DropBuildStash | null> {
+  try {
+    if (typeof indexedDB === 'undefined') return null;
+    const record = await runStoreOperation<DropBuildStash | undefined>('readonly', store =>
+      store.get(STASH_KEY)
+    );
+    const zipFile = record && rehydrateZipFile(record.zipFile);
+    if (!record || !zipFile) return null;
+    if (Date.now() - record.createdAt > STASH_TTL_MS) {
+      await clearDropStash();
+      return null;
+    }
+    return { ...record, zipFile };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The archive back out of storage as a real `File`. Structured clone should
+ * preserve File identity, but implementations vary in whether the name and
+ * prototype survive — and the build upload needs both (the multipart field is
+ * named by the File). A Blob-shaped survivor is rewrapped; anything else is
+ * treated as a corrupt record.
+ */
+function rehydrateZipFile(stored: unknown): File | null {
+  if (stored instanceof File && stored.name) return stored;
+  if (stored instanceof Blob || (stored && typeof (stored as Blob).arrayBuffer === 'function')) {
+    return new File([stored as Blob], 'source.zip', { type: 'application/zip' });
+  }
+  return null;
+}
+
+/** Remove the stash and its marker. Idempotent; never throws. */
+export async function clearDropStash(): Promise<void> {
+  try {
+    clearMarker();
+  } catch {
+    // storage disabled — nothing to clear
+  }
+  try {
+    if (typeof indexedDB === 'undefined') return;
+    await runStoreOperation('readwrite', store => store.delete(STASH_KEY));
+  } catch {
+    // best effort — an orphaned record expires via its TTL
+  }
+}
+
+/** Cheap synchronous check so page loads don't open IndexedDB just to look for a stash. */
+export function hasDropStashMarker(): boolean {
+  try {
+    const marker = localStorage.getItem(MARKER_KEY);
+    if (!marker) return false;
+    const { expiresAt } = JSON.parse(marker) as { expiresAt?: number };
+    if (typeof expiresAt !== 'number' || Date.now() > expiresAt) {
+      clearMarker();
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}