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

package/dist/components/preact/DropZone/useDropDeploy.js

@@ -1,22 +1,22 @@
-import { d as R, A as S, y as nt } from "../../../chunks/hooks.module.DRcxknIz.js";
-import { humanizeDropError as rt, isNotAuthenticatedError as O } from "../../../drop-core/errors.js";
+import { d as O, A as S, y as nt } from "../../../chunks/hooks.module.DRcxknIz.js";
+import { humanizeDropError as rt, isNotAuthenticatedError as R } from "../../../drop-core/errors.js";
 import { DROPZONE_EVENTS as c } from "../../../drop-core/analytics.js";
 import { renameSingleNonIndexHtmlToIndex as at, getSingleNonIndexHtmlFileName as ot, hasMultipleHtmlFilesWithoutIndex as st } from "../../../drop-core/readFiles.js";
 import { detectBuild as dt } from "../../../drop-core/detectBuild.js";
-import { zipFiles as lt } from "../../../drop-core/zip.js";
-import { AnonymousDropClient as ut } from "../../../drop-core/client.js";
+import { zipFiles as ut } from "../../../drop-core/zip.js";
+import { AnonymousDropClient as lt } from "../../../drop-core/client.js";
 import { AuthenticatedDropClient as ct } from "../../../drop-core/authedDropClient.js";
 import { AuthenticatedBuildClient as mt } from "../../../drop-core/buildClient.js";
 import { deployZippedBuild as ft, deployFiles as v } from "../../../drop-core/deploy.js";
-import { hasDropStashMarker as gt, loadDropStash as ht, clearDropStash as E, saveDropStash as pt } from "../../../drop-core/buildStash.js";
-function I(l) {
-  switch (l.phase) {
+import { hasDropStashMarker as gt, loadDropStash as ht, clearDropStash as y, saveDropStash as pt } from "../../../drop-core/buildStash.js";
+function I(u) {
+  switch (u.phase) {
     case "zipping":
       return { kind: "zipping" };
     case "creating":
       return { kind: "creating" };
     case "uploading":
-      return { kind: "uploading", uploaded: l.uploaded ?? 0, total: l.total ?? 0 };
+      return { kind: "uploading", uploaded: u.uploaded ?? 0, total: u.total ?? 0 };
     case "building":
       return { kind: "building" };
     case "processing":
@@ -24,192 +24,197 @@ function I(l) {
       return { kind: "processing" };
   }
 }
-function wt(l) {
-  const m = ot(l);
-  return m ? `No index.html found — "${m}" won’t be served at the site root.` : st(l) ? "No index.html found — your site may not have a landing page." : null;
+function wt(u) {
+  const m = ot(u);
+  return m ? `No index.html found — "${m}" won’t be served at the site root.` : st(u) ? "No index.html found — your site may not have a landing page." : null;
 }
-function St(l, m) {
+function St(u, m) {
   try {
-    localStorage.setItem("drop-token", l), localStorage.setItem("dropSiteName", m);
+    localStorage.setItem("drop-token", u), localStorage.setItem("dropSiteName", m);
   } catch {
   }
 }
-function Pt({
-  apiBase: l,
+function Ft({
+  apiBase: u,
   client: m,
   claimUrl: z,
-  siteDashboardUrl: H,
-  buildSignupUrl: W,
-  buildClient: Y,
+  siteDashboardUrl: Y,
+  buildSignupUrl: H,
+  buildClient: W,
   authenticatedDropClient: M,
   getUploadToken: p,
   proxyBase: N,
   accountSlug: A,
-  buildDeployUrl: C,
+  buildDeployUrl: L,
   waitForBuild: Z,
-  onBuildRequired: L,
-  onBuildSignupHandoff: P,
+  onBuildRequired: C,
+  onBuildSignupHandoff: F,
   resumeStashedBuilds: $ = !0,
-  onDeploy: k,
+  onDeploy: _,
   onBuildDeploy: f,
   onError: g,
   track: q
 }) {
-  const u = (n, t) => (
+  const l = (n, i) => (
     // The event interfaces carry no index signature, hence the cast to TrackFn's record.
-    q(n, t)
-  ), [b, a] = R({ kind: "idle" }), [U, _] = R(null), j = S(m ?? new ut(l)).current, w = S(
-    Y ?? (p ? new mt({ proxyBase: N, getUploadToken: p, accountSlug: A }) : null)
-  ).current, y = S(
+    q(n, i)
+  ), [k, a] = O({ kind: "idle" }), [U, b] = O(null), j = S(m ?? new lt(u)).current, w = S(
+    W ?? (p ? new mt({ proxyBase: N, getUploadToken: p, accountSlug: A }) : null)
+  ).current, D = S(
     M ?? (p ? new ct({ proxyBase: N, getUploadToken: p, accountSlug: A }) : null)
-  ).current, J = b.kind !== "idle" && b.kind !== "error";
-  async function x(n, t) {
+  ).current, J = k.kind !== "idle" && k.kind !== "error";
+  async function P(n, i) {
     try {
-      const { site: i, build: r, buildSettings: o, url: e } = await ft(n, t, {
+      const { site: e, build: r, buildSettings: o, url: t } = await ft(n, i, {
         onProgress: (s) => a(I(s)),
         waitForBuild: Z
       });
       return {
-        url: e,
-        siteName: i.name,
-        siteId: i.id,
+        url: t,
+        siteName: e.name,
+        siteId: e.id,
         buildId: r.id,
         deployId: r.deploy_id,
         buildSettings: o
       };
-    } catch (i) {
-      if (O(i)) return null;
-      throw i;
+    } catch (e) {
+      if (R(e)) return null;
+      throw e;
     }
   }
-  async function Q(n, t, i) {
-    _(null), a({ kind: "reading" });
-    const r = i.length ? { file_types: i } : {}, o = (e, s, d) => {
-      a({ kind: "error", message: e }), u(c.DEPLOY_FAILED, { method: t, reason: s, ...r, ...d }), g == null || g({ message: e, reason: s });
+  async function Q(n, i, e) {
+    b(null), a({ kind: "reading" });
+    const r = e.length ? { file_types: e } : {}, o = (t, s, d) => {
+      a({ kind: "error", message: t }), l(c.DEPLOY_FAILED, { method: i, reason: s, ...r, ...d }), g == null || g({ message: t, reason: s });
     };
     try {
-      const e = at(await n());
-      if (!e.length) {
+      const t = at(await n());
+      if (!t.length) {
         o("No files found to deploy.", "No files found to deploy.", { file_count: 0 });
         return;
       }
-      t === "drag" && u(c.FILES_DROPPED, {
-        method: t,
-        file_count: e.length,
+      i === "drag" && l(c.FILES_DROPPED, {
+        method: i,
+        file_count: t.length,
         ...r
       });
-      const s = { source: t, fileCount: e.length, typeProps: r }, d = dt(e);
-      d.buildRequired ? await T(e, d, s) : await G(e, s);
-    } catch (e) {
-      const s = e instanceof Error ? e.message : String(e);
-      o(rt(e), s);
+      const s = { source: i, fileCount: t.length, typeProps: r }, d = dt(t);
+      d.buildRequired ? await T(t, d, s) : await G(t, s);
+    } catch (t) {
+      const s = t instanceof Error ? t.message : String(t);
+      o(rt(t), s);
     }
   }
-  async function T(n, t, { source: i, fileCount: r, typeProps: o }) {
-    if (u(c.BUILD_REQUIRED, {
-      method: i,
-      reason: t.reason,
+  async function T(n, i, { source: e, fileCount: r, typeProps: o }) {
+    if (l(c.BUILD_REQUIRED, {
+      method: e,
+      reason: i.reason,
       file_count: r,
       ...o
-    }), L) {
-      a({ kind: "idle" }), L(t);
+    }), C) {
+      a({ kind: "idle" }), C(i);
       return;
     }
-    let e = !1;
+    let t = !1;
     if (w) {
       a({ kind: "zipping" });
-      const s = await lt(n), d = await x(w, s);
+      const s = await ut(n), d = await P(w, s);
       if (d) {
-        a({ kind: "redirecting", target: "build" }), u(c.BUILD_DEPLOY_SUCCEEDED, {
-          method: i,
-          reason: t.reason,
+        a({ kind: "redirecting", target: "build" }), l(c.BUILD_DEPLOY_SUCCEEDED, {
+          method: e,
+          reason: i.reason,
           site_name: d.siteName,
           file_count: r,
           ...d.buildSettings ? { framework: d.buildSettings.framework } : {},
           ...o
-        }), f == null || f(d), window.location.assign(C(d));
+        }), f == null || f(d), window.location.assign(L(d));
         return;
       }
-      e = await pt(s.file, s.buildSettings), e && u(c.PROJECT_STASHED, {
-        method: i,
-        reason: t.reason,
+      t = await pt(s.file, s.buildSettings), t && l(c.PROJECT_STASHED, {
+        method: e,
+        reason: i.reason,
         file_count: r,
         ...o
       });
     }
-    if (P) {
-      a({ kind: "idle" }), P({ stashed: e, detection: t });
+    if (t || l(c.DEPLOY_FAILED, {
+      method: e,
+      reason: "anonymous_build_not_supported",
+      file_count: r,
+      ...o
+    }), F) {
+      a({ kind: "idle" }), F({ stashed: t, detection: i });
       return;
     }
-    a({ kind: "redirecting", target: "signup" }), window.location.assign(W);
+    a({ kind: "redirecting", target: "signup" }), window.location.assign(H);
   }
-  async function V(n, t) {
+  async function V(n, i) {
     try {
-      return await v(n, t, {
-        onProgress: (i) => a(I(i))
+      return await v(n, i, {
+        onProgress: (e) => a(I(e))
       });
-    } catch (i) {
-      if (O(i)) return null;
-      throw i;
+    } catch (e) {
+      if (R(e)) return null;
+      throw e;
     }
   }
-  async function G(n, { source: t, fileCount: i, typeProps: r }) {
-    _(wt(n));
-    const o = y ? await V(y, n) : null, e = o !== null, s = y !== null && !e, d = o ?? await v(j, n, {
-      onProgress: (it) => a(I(it))
-    }), { url: et, token: D, deploy: h } = d;
-    e || St(D, h.subdomain), a({ kind: "redirecting", target: e ? "dashboard" : "claim" }), u(c.DEPLOY_SUCCEEDED, {
-      method: t,
+  async function G(n, { source: i, fileCount: e, typeProps: r }) {
+    b(wt(n));
+    const o = D ? await V(D, n) : null, t = o !== null, s = D !== null && !t, d = o ?? await v(j, n, {
+      onProgress: (et) => a(I(et))
+    }), { url: it, token: E, deploy: h } = d;
+    t || St(E, h.subdomain), a({ kind: "redirecting", target: t ? "dashboard" : "claim" }), l(c.DEPLOY_SUCCEEDED, {
+      method: i,
       site_name: h.subdomain,
-      file_count: i,
-      authenticated: e,
+      file_count: e,
+      authenticated: t,
       ...s ? { auth_fallback: !0 } : {},
       ...r
-    }), k == null || k({
-      url: et,
-      ...e ? {} : { token: D },
+    }), _ == null || _({
+      url: it,
+      ...t ? {} : { token: E },
       siteName: h.subdomain,
       siteId: h.id,
-      authenticated: e
-    }), K(e, h.subdomain, D);
+      authenticated: t
+    }), K(t, h.subdomain, E);
   }
-  function K(n, t, i) {
-    n ? window.location.assign(H(t)) : window.location.assign(`${z(t)}#drop_token=${i}`);
+  function K(n, i, e) {
+    n ? window.location.assign(Y(i)) : window.location.assign(`${z(i)}#drop_token=${e}`);
   }
   async function X(n) {
-    const t = await ht();
-    if (!t) {
-      await E();
+    const i = await ht();
+    if (!i) {
+      await y();
       return;
     }
-    u(c.RESUMED, {}), a({ kind: "creating" });
-    const i = { file: t.zipFile, buildSettings: t.buildSettings };
+    l(c.RESUMED, {}), a({ kind: "creating" });
+    const e = { file: i.zipFile, buildSettings: i.buildSettings };
     let r;
     try {
-      r = await x(n, i);
+      r = await P(n, e);
     } catch (o) {
-      await E(), B(o instanceof Error ? o.message : String(o));
+      await y(), B(o instanceof Error ? o.message : String(o));
       return;
     }
     if (!r) {
       a({ kind: "idle" });
       return;
     }
-    await E(), a({ kind: "redirecting", target: "build" }), f == null || f(r), window.location.assign(C(r));
+    await y(), a({ kind: "redirecting", target: "build" }), f == null || f(r), window.location.assign(L(r));
   }
   function B(n) {
-    const t = "We couldn’t automatically deploy your project. Drop it again to publish it.";
-    a({ kind: "error", message: t }), u(c.DEPLOY_FAILED, { reason: "resume_failed" }), g == null || g({ message: t, reason: n });
+    const i = "We couldn’t automatically deploy your project. Drop it again to publish it.";
+    a({ kind: "error", message: i }), l(c.DEPLOY_FAILED, { reason: "resume_failed" }), g == null || g({ message: i, reason: n });
   }
-  const F = S(!1);
+  const x = S(!1);
   nt(() => {
-    F.current || !$ || !w || !gt() || (F.current = !0, X(w));
+    x.current || !$ || !w || !gt() || (x.current = !0, X(w));
   }, []);
   function tt() {
-    _(null), a({ kind: "idle" });
+    b(null), a({ kind: "idle" });
   }
-  return { status: b, warning: U, busy: J, deploy: Q, reset: tt };
+  return { status: k, warning: U, busy: J, deploy: Q, reset: tt };
 }
 export {
-  Pt as useDropDeploy
+  Ft as useDropDeploy
 };

package/dist/drop-core/buildStash.js

@@ -1,17 +1,20 @@
-const f = "netlify-drop";
+const l = "netlify-drop";
 const s = "build-stash", c = "latest", i = "dropBuildStash";
-const S = (e) => Promise.race([
+const f = (e) => Promise.race([
   e,
   new Promise((r, t) => {
     setTimeout(() => t(new Error("IndexedDB operation timed out")), 3e3);
   })
-]), d = () => new Promise((e, r) => {
-  const t = indexedDB.open(f, 1);
+]), S = () => new Promise((e, r) => {
+  const t = indexedDB.deleteDatabase(l);
+  t.onsuccess = () => e(), t.onblocked = () => e(), t.onerror = () => r(t.error);
+}), p = () => new Promise((e, r) => {
+  const t = indexedDB.open(l, 1);
   t.onupgradeneeded = () => {
     t.result.createObjectStore(s);
   }, t.onsuccess = () => e(t.result), t.onerror = () => r(t.error);
-}), u = (e, r) => S(
-  d().then(
+}), u = (e, r) => f(
+  p().then(
     (t) => new Promise((o, a) => {
       const n = r(t.transaction(s, e).objectStore(s));
       n.onsuccess = () => {
@@ -21,33 +24,42 @@ const S = (e) => Promise.race([
       };
     })
   )
-), p = async (e) => {
+), y = async (e) => {
   const { quota: r, usage: t } = await navigator.storage.estimate();
   return r !== void 0 && t !== void 0 && r - t > e * 2;
 }, T = () => {
-  localStorage.setItem(i, JSON.stringify({ expiresAt: Date.now() + 864e5 }));
-}, l = () => {
+  localStorage.setItem(
+    i,
+    JSON.stringify({ value: "true", expiry: Date.now() + 864e5 })
+  );
+}, d = () => {
   localStorage.removeItem(i);
 };
-async function A(e, r = null) {
+async function O(e, r = null) {
   var t;
   try {
-    if (typeof indexedDB > "u" || !((t = navigator.storage) != null && t.estimate) || e.size > 209715200 || !await p(e.size))
+    if (typeof indexedDB > "u" || !((t = navigator.storage) != null && t.estimate) || e.size > 209715200 || !await y(e.size))
       return !1;
-    const o = { zipFile: e, buildSettings: r, createdAt: Date.now() };
+    const o = {
+      // Round-trip through JSON so an injected detector's richer object can't
+      // fail the structured clone the put() below performs.
+      buildSettings: r && JSON.parse(JSON.stringify(r)),
+      zipFile: e,
+      createdAt: Date.now()
+    };
     return await u("readwrite", (a) => a.put(o, c)), T(), !0;
   } catch {
     return !1;
   }
 }
-async function D() {
+async function w() {
   try {
     if (typeof indexedDB > "u") return null;
     const e = await u(
       "readonly",
       (t) => t.get(c)
     ), r = e && _(e.zipFile);
-    return !e || !r ? null : Date.now() - e.createdAt > 864e5 ? (await y(), null) : { ...e, zipFile: r };
+    return !e || !r ? null : Date.now() - e.createdAt > 864e5 ? (await D(), null) : { ...e, zipFile: r };
   } catch {
     return null;
   }
@@ -55,30 +67,30 @@ async function D() {
 function _(e) {
   return e instanceof File && e.name ? e : e instanceof Blob || e && typeof e.arrayBuffer == "function" ? new File([e], "source.zip", { type: "application/zip" }) : null;
 }
-async function y() {
+async function D() {
   try {
-    l();
+    d();
   } catch {
   }
   try {
     if (typeof indexedDB > "u") return;
-    await u("readwrite", (e) => e.delete(c));
+    await u("readwrite", (e) => e.delete(c)), await f(S());
   } catch {
   }
 }
-function O() {
+function E() {
   try {
     const e = localStorage.getItem(i);
     if (!e) return !1;
-    const { expiresAt: r } = JSON.parse(e);
-    return typeof r != "number" || Date.now() > r ? (l(), !1) : !0;
+    const { value: r, expiry: t } = JSON.parse(e);
+    return r !== "true" || typeof t != "number" || Date.now() > t ? (d(), !1) : !0;
   } catch {
     return !1;
   }
 }
 export {
-  y as clearDropStash,
-  O as hasDropStashMarker,
-  D as loadDropStash,
-  A as saveDropStash
+  D as clearDropStash,
+  E as hasDropStashMarker,
+  w as loadDropStash,
+  O as saveDropStash
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/spark-ui",
   "description": "Assets, design tokens, components, and utilities",
-  "version": "1.31.0-alpha.6",
+  "version": "1.31.0-alpha.7",
   "type": "module",
   "main": "dist/components/preact/index.js",
   "types": "dist/components/preact/index.d.ts",

package/packages/components/preact/DropZone/useDropDeploy.test.ts

@@ -287,6 +287,18 @@ describe('build-required drops', () => {
 
     expect(saveDropStash).not.toHaveBeenCalled();
     expect(harness.assigned).toEqual(['https://app.netlify.com/signup?next=/drop']);
+    // Nothing was stashed, so the drop is lost rather than deferred — reported
+    // with the same reason react-ui uses for its own build bounce.
+    const failed = harness.events.find(e => e.event === DROPZONE_EVENTS.DEPLOY_FAILED);
+    expect(failed?.props).toMatchObject({ reason: 'anonymous_build_not_supported' });
+  });
+
+  it('does not report a loss when the archive was stashed', async () => {
+    const harness = mountHook({ buildClient: makeBuildClient('no-auth'), getUploadToken: async () => null });
+    await harness.api.deploy(async () => buildFiles(), 'drag', []);
+    await settle();
+
+    expect(harness.events.map(e => e.event)).not.toContain(DROPZONE_EVENTS.DEPLOY_FAILED);
   });
 
   it('cedes everything to onBuildRequired when set', async () => {

package/packages/components/preact/DropZone/useDropDeploy.ts

@@ -365,6 +365,18 @@ export function useDropDeploy({
     // Without build wiring nothing here could deploy a stash later, so nothing
     // is stashed — the hand-off is all that's left.
 
+    if (!stashed) {
+      // Nothing survived the hand-off, so this drop is genuinely lost rather
+      // than deferred. Reported with the app's own bounce reason so both
+      // surfaces count it the same way.
+      emit(DROPZONE_EVENTS.DEPLOY_FAILED, {
+        method: source,
+        reason: 'anonymous_build_not_supported',
+        file_count: fileCount,
+        ...typeProps,
+      });
+    }
+
     if (onBuildSignupHandoff) {
       // The consumer owns the hand-off (e.g. an auth popup that keeps the
       // visitor on this page); back to idle so the zone stays usable.

package/packages/drop-core/README.md

@@ -1,20 +1,300 @@
 # 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.
+The engine behind Netlify Drop, without any UI attached.
 
-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.
+Give it the files a visitor dropped on your page and it will read them, work out
+whether the project needs a build, and deploy it — either anonymously, so the
+visitor claims the site afterwards, or straight into their Netlify account if
+they're signed in.
 
-## Conventions
+There's no Preact, React, or DOM-framework dependency anywhere in here, so it
+can sit under whatever interface you're building. If you want the drop zone
+_and_ the UI, use the [`DropZone` component](../components/preact/DropZone)
+instead — it's a thin view over this package.
 
-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.
+## Install
+
+drop-core ships inside `@netlify/spark-ui`:
+
+```sh
+npm install @netlify/spark-ui
+```
+
+```ts
+import { deployFiles, AnonymousDropClient } from '@netlify/spark-ui/drop-core';
+```
+
+## Quick start
+
+The shortest useful thing: accept a dropped folder and deploy it anonymously.
+
+```ts
+import { AnonymousDropClient, deployFiles, readDataTransfer } from '@netlify/spark-ui/drop-core';
+
+zone.addEventListener('drop', async event => {
+  event.preventDefault();
+  if (!event.dataTransfer) return;
+
+  // Read the DataTransfer first. The browser detaches it once the event turn
+  // ends, so anything that touches it has to run before you await elsewhere.
+  const files = await readDataTransfer(event.dataTransfer);
+
+  const { deploy, token, url } = await deployFiles(new AnonymousDropClient(), files, {
+    onProgress: e => console.log(e.phase, e.uploaded, '/', e.total),
+  });
+
+  console.log('live at', url);
+
+  // Anonymous sites are unclaimed. Send the visitor to the claim page with
+  // the token in the fragment — localStorage doesn't cross origins.
+  location.assign(`https://app.netlify.com/drop/${deploy.subdomain}#drop_token=${token}`);
+});
+```
+
+`readDataTransfer` handles a dropped folder, a zip, or a multi-file selection,
+strips junk like `__MACOSX` and dotfiles, flattens a single wrapping folder, and
+sha1-digests each file. A lone `.html` file is renamed to `index.html` so it
+serves at the site root.
+
+For a file picker instead of a drop, use `readFileList(input.files)`.
+
+## Deploying into a signed-in account
+
+Swap the client. `AuthenticatedDropClient` creates the site in the visitor's own
+account, so there's no claim step — you can send them straight to their new
+project.
+
+JSON calls ride a same-origin `/access-control` proxy on their session cookie;
+file uploads go direct to `api.netlify.com` on a bearer token you mint:
+
+```ts
+import {
+  AuthenticatedDropClient,
+  deployFiles,
+  isNotAuthenticatedError,
+} from '@netlify/spark-ui/drop-core';
+
+const client = new AuthenticatedDropClient({
+  getUploadToken: async () => {
+    const res = await fetch('/access-control/generate-access-control-token', {
+      credentials: 'include',
+    });
+    if (!res.ok) return null; // `null` means "no session"
+    return (await res.json()).accessControlToken ?? null;
+  },
+});
+
+try {
+  const { deploy } = await deployFiles(client, files);
+  location.assign(`https://app.netlify.com/projects/${deploy.subdomain}`);
+} catch (err) {
+  if (isNotAuthenticatedError(err)) {
+    // No session after all. Nothing was created, so falling back to an
+    // anonymous deploy here is safe.
+    return deployAnonymously(files);
+  }
+  throw err;
+}
+```
+
+Pass `accountSlug` if you want the site created in a specific team rather than
+the visitor's default one.
+
+## Projects that need a build
+
+A dropped Astro or Next project can't be served as static files. `detectBuild`
+tells you, cheaply, by looking at `netlify.toml`, `package.json`, and the
+zero-config functions directories:
+
+```ts
+import { detectBuild, deployBuild, AuthenticatedBuildClient } from '@netlify/spark-ui/drop-core';
+
+const detection = detectBuild(files);
+
+if (!detection.buildRequired) {
+  await deployFiles(client, files);
+} else {
+  const build = await deployBuild(new AuthenticatedBuildClient({ getUploadToken }), files, {
+    onProgress: e => setPhase(e.phase),
+  });
+  location.assign(`https://app.netlify.com/projects/${build.site.name}`);
+}
+```
+
+`detection.reason` tells you which signal fired (`netlify-toml-build`,
+`package-json-build-script`, `framework-dependency`, `functions-directory`) —
+useful for analytics or for explaining the decision to the visitor.
+
+`deployBuild` zips the project, creates the site, and hands the archive to
+Netlify's build system. It returns as soon as the build is enqueued; pass
+`waitForBuild: true` if you'd rather wait for it to finish, which is also the
+only way a failing build's own error message reaches you.
+
+If the project has no `[build]` table of its own, drop-core infers one from the
+detected framework and writes it into the archive — but only when it's confident
+about both the command and the publish directory, since guessing the publish
+directory wrong ships your source instead of your site.
+
+Building requires a signed-in visitor: there's no anonymous build API.
+
+## Carrying a drop across signup
+
+If a visitor drops a project that needs a build and _isn't_ signed in, you don't
+have to throw their work away. Stash the archive, send them to signup, and
+deploy it when they come back:
+
+```ts
+import {
+  clearDropStash,
+  deployZippedBuild,
+  hasDropStashMarker,
+  loadDropStash,
+  saveDropStash,
+  zipFiles,
+} from '@netlify/spark-ui/drop-core';
+
+// On the way out:
+const archive = await zipFiles(files);
+await saveDropStash(archive.file, archive.buildSettings);
+location.assign('https://app.netlify.com/signup?next=/drop');
+
+// On any later page load, once they're back and signed in:
+if (hasDropStashMarker()) {
+  const stash = await loadDropStash();
+  if (stash) {
+    const built = await deployZippedBuild(buildClient, {
+      file: stash.zipFile,
+      buildSettings: stash.buildSettings,
+    });
+    await clearDropStash();
+    location.assign(`https://app.netlify.com/projects/${built.site.name}`);
+  }
+}
+```
+
+The archive lives in IndexedDB for 24 hours, with a small localStorage marker so
+an ordinary page load can ask "is there anything waiting?" without opening a
+database. Storage is per-origin, so whatever you hand off to must bring the
+visitor back to the same origin.
+
+Only consume the stash once the visitor is genuinely authenticated — if they
+come back still signed out, leave it alone for next time.
+
+## Reporting progress
+
+Every deploy function takes an `onProgress` callback and reports a phase:
+
+| Phase        | Meaning                                    |
+| ------------ | ------------------------------------------ |
+| `zipping`    | Packing the project (build path only)      |
+| `creating`   | Creating the site and deploy               |
+| `uploading`  | Uploading files, with `uploaded` / `total` |
+| `processing` | Uploaded; Netlify is making the site live  |
+| `building`   | Build running (build path only)            |
+| `ready`      | Done                                       |
+
+Static deploys run `creating → uploading → processing → ready`; build deploys
+run `zipping → creating → uploading → building → ready`. Only `uploading` on the
+static path carries file counts — a build zip is a single request, and the
+browser can't report progress within it.
+
+## Handling failures
+
+Each failure mode has its own error class carrying a stable `code`:
+`UnsupportedDropError`, `NotAuthenticatedError`, `SiteCreateError`,
+`BuildCreateError`, `BuildFailedError`, `BuildTimeoutError`,
+`DeployFailedError`, `DeployTimeoutError`.
+
+For anything you're showing a person, `humanizeDropError` turns any of them —
+plus network failures and raw HTTP statuses — into a sentence you can display:
+
+```ts
+import { humanizeDropError } from '@netlify/spark-ui/drop-core';
+
+catch (err) {
+  showError(humanizeDropError(err));
+  track('deploy_failed', { reason: String(err) }); // keep the raw one for logs
+}
+```
+
+To branch on control flow rather than display, use the `isNotAuthenticatedError`
+predicate rather than `instanceof`. This package ships as both raw TypeScript
+and compiled output, so two copies of the same class can exist in one app and
+`instanceof` will quietly miss.
+
+## Analytics
+
+`DROPZONE_EVENTS` holds the canonical event names, and
+`DropZoneEventProperties` maps each one to its payload shape, so you can wire
+your own provider without hand-writing strings:
+
+```ts
+import { DROPZONE_EVENTS } from '@netlify/spark-ui/drop-core';
+
+track(DROPZONE_EVENTS.DEPLOY_SUCCEEDED, { method: 'drag', file_count: 12 });
+```
+
+## Good to know
+
+- **Uploads can't go through the `/access-control` proxy.** `PUT` isn't
+  allowlisted and bodies cap around 6 MB, so file uploads always go direct to
+  `api.netlify.com` on a bearer token.
+- **Upload tokens are short-lived off the app origin** — 30 seconds, against the
+  app's 300. Static deploys re-mint as they go, but a build zip is one request,
+  so an upload slower than that will fail. Raising the limit is a platform-side
+  change.
+- **`NotAuthenticatedError` only ever means "nothing was created yet."** It's
+  your signal that an anonymous retry is safe. Nothing throws it once a site
+  exists, because falling back then would leave an empty project behind and
+  deploy a duplicate.
+- **`deploy_id` is not `deploy.id`.** File uploads and readiness polling key off
+  `deploy_id` (BSON); `deploy.id` is the site's UUID. Mixing them up produces a
+  misleading 401.
+- **`detectBuild` is deliberately lightweight** — two config files and the
+  functions directories, no framework-detection dependency. If you already have
+  something better, inject your own detection and use `deployBuild` directly.
+
+## Reference
+
+**Reading files**
+
+| Export                 | Purpose                                                 |
+| ---------------------- | ------------------------------------------------------- |
+| `readDataTransfer(dt)` | A drop: folder, zip, or loose files → `ProcessedFile[]` |
+| `readFileList(files)`  | The same, from an `<input type="file">`                 |
+| `getFileTypes(files)`  | Distinct MIME types, for analytics                      |
+
+**Detecting and packing**
+
+| Export                      | Purpose                                           |
+| --------------------------- | ------------------------------------------------- |
+| `detectBuild(files)`        | `{ buildRequired, reason }`                       |
+| `inferBuildSettings(files)` | Build command + publish dir, or `null` if unsure  |
+| `zipFiles(files)`           | The source archive, plus any synthesised settings |
+
+**Deploying**
+
+| Export                                 | Purpose                                   |
+| -------------------------------------- | ----------------------------------------- |
+| `deployFiles(client, files, opts)`     | Static deploy                             |
+| `deployBuild(client, files, opts)`     | Zip, create site, enqueue build           |
+| `deployZippedBuild(client, zip, opts)` | Same, from an archive you already have    |
+| `AnonymousDropClient`                  | Claim-flow deploys, no session needed     |
+| `AuthenticatedDropClient`              | Static deploys into the visitor's account |
+| `AuthenticatedBuildClient`             | Builds in the visitor's account           |
+
+**Stash**
+
+| Export                              | Purpose                                     |
+| ----------------------------------- | ------------------------------------------- |
+| `saveDropStash(zip, buildSettings)` | Store an archive for after signup           |
+| `hasDropStashMarker()`              | Cheap synchronous "is anything waiting?"    |
+| `loadDropStash()`                   | The archive, or `null` if expired or absent |
+| `clearDropStash()`                  | Remove it; idempotent, never throws         |
+
+Anything not exported from `index.ts` is internal and may change.
+
+## Contributing
 
 ### Boundaries
 
@@ -33,14 +313,14 @@ deliberately differ, that's recorded too, so it isn't re-litigated by accident.
 
 ### 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`                             |
+| 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` — **append-only** | `DROPZONE_EVENTS` (renames fail `analytics.test.ts`)          |
+| Error predicates   | `isXError(err)`                         | `isNotAuthenticatedError`                                     |
+| Files              | filename = main export                  | `detectBuild.ts`, `buildStash.ts`                             |
 
 ### Comments
 
@@ -55,9 +335,9 @@ deliberately differ, that's recorded too, so it isn't re-litigated by accident.
   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).
+  test that pins it.
 - **No `@param`/`@returns`.** Types carry the shape; JSDoc carries rationale
-  and edge cases. (react-dropzone: zero `@param` across its entire source.)
+  and edge cases.
 - File-header purpose blocks only where the filename undersells the contents.
 
 ### Errors
@@ -71,21 +351,13 @@ deliberately differ, that's recorded too, so it isn't re-litigated by accident.
   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.
+- **Humanized copy lives in `humanizeDropError`, in this package.** 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.
+  data, so the curve is overridable); **400/422 never retry** — the request
+  itself is wrong.
+
+### Tests
+
+Colocated as `*.test.ts` — the Vite build glob ignores `**/*.test.*`, and
+anything else under `packages/` gets published. `npm test` runs the suite.

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

@@ -47,6 +47,25 @@ describe('buildStash', () => {
     expect(await stash?.zipFile.text()).toBe('zip-bytes');
   });
 
+  // Same key AND same value shape as react-ui's setWithExpiry, so the app can
+  // adopt this module without stranding a marker its own code already wrote.
+  it('writes the marker in react-ui’s { value, expiry } shape', async () => {
+    await saveDropStash(zip());
+    const marker = JSON.parse(localStorage.getItem('dropBuildStash') as string);
+    expect(marker.value).toBe('true');
+    expect(marker.expiry).toBeGreaterThan(Date.now());
+    expect(marker.expiry).toBeLessThanOrEqual(Date.now() + 24 * 60 * 60 * 1000);
+  });
+
+  // The row delete is what makes the stash unusable; dropping the database is
+  // cleanup, so a 200MB archive doesn't linger in the visitor's profile.
+  it('drops the database, not just the row, once the stash is consumed', async () => {
+    const deleteDatabase = vi.spyOn(indexedDB, 'deleteDatabase');
+    await saveDropStash(zip());
+    await clearDropStash();
+    expect(deleteDatabase).toHaveBeenCalledWith('netlify-drop');
+  });
+
   it('clears the stash and marker idempotently', async () => {
     await saveDropStash(zip());
     await clearDropStash();

package/packages/drop-core/buildStash.ts

@@ -35,6 +35,16 @@ const withTimeout = <T>(promise: Promise<T>): Promise<T> =>
     }),
   ]);
 
+// Resolves on `blocked` too: another tab holding the database open is not worth
+// stalling the caller for, and the row delete already made the stash unusable.
+const deleteDatabase = (): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const request = indexedDB.deleteDatabase(DB_NAME);
+    request.onsuccess = () => resolve();
+    request.onblocked = () => resolve();
+    request.onerror = () => reject(request.error);
+  });
+
 const openDatabase = (): Promise<IDBDatabase> =>
   new Promise((resolve, reject) => {
     const request = indexedDB.open(DB_NAME, DB_VERSION);
@@ -74,8 +84,13 @@ const hasEnoughQuota = async (bytes: number): Promise<boolean> => {
 
 // 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.
+// `{ value, expiry }` is react-ui's setWithExpiry shape — same key, same shape,
+// so the app can adopt this module without stranding a marker it already wrote.
 const setMarker = () => {
-  localStorage.setItem(MARKER_KEY, JSON.stringify({ expiresAt: Date.now() + STASH_TTL_MS }));
+  localStorage.setItem(
+    MARKER_KEY,
+    JSON.stringify({ value: 'true', expiry: Date.now() + STASH_TTL_MS })
+  );
 };
 
 const clearMarker = () => {
@@ -96,7 +111,13 @@ export async function saveDropStash(
     ) {
       return false;
     }
-    const record: DropBuildStash = { zipFile, buildSettings, createdAt: Date.now() };
+    const record: DropBuildStash = {
+      // Round-trip through JSON so an injected detector's richer object can't
+      // fail the structured clone the put() below performs.
+      buildSettings: buildSettings && JSON.parse(JSON.stringify(buildSettings)),
+      zipFile,
+      createdAt: Date.now(),
+    };
     await runStoreOperation('readwrite', store => store.put(record, STASH_KEY));
     setMarker();
     return true;
@@ -146,7 +167,11 @@ export async function clearDropStash(): Promise<void> {
   }
   try {
     if (typeof indexedDB === 'undefined') return;
+    // The row delete is what guarantees the stash can't come back; dropping the
+    // database afterwards is cleanup, so the visitor's project source doesn't
+    // sit in their profile once we're done with it. It reappears on the next drop.
     await runStoreOperation('readwrite', store => store.delete(STASH_KEY));
+    await withTimeout(deleteDatabase());
   } catch {
     // best effort — an orphaned record expires via its TTL
   }
@@ -157,8 +182,8 @@ 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) {
+    const { value, expiry } = JSON.parse(marker) as { value?: string; expiry?: number };
+    if (value !== 'true' || typeof expiry !== 'number' || Date.now() > expiry) {
       clearMarker();
       return false;
     }

package/packages/drop-core/constants.ts

@@ -13,7 +13,7 @@ export const DEFAULT_POLL_INTERVAL_MS = 1000;
 // How long to keep polling before giving up: 10 minutes
 export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 
-// Concurrent file uploads (matches netlify-cli's deploy engine)
+// Concurrent file uploads
 export const MAX_CONCURRENT_UPLOADS = 5;
 
 // Reuse window for a minted upload token: 20s (server TTL is 30s; the gap is