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

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

@@ -112,7 +112,6 @@ interface UseDropDeployOptions {
   track: TrackFn;
 }
 
-/** Map a low-level deploy progress event onto our UI status. */
 function progressToStatus(e: DeployProgress): DeployStatus {
   switch (e.phase) {
     case 'zipping':
@@ -129,7 +128,7 @@ function progressToStatus(e: DeployProgress): DeployStatus {
   }
 }
 
-/** Inspect the file set and return a non-blocking index.html warning, if any. */
+/** Advisory only — a missing index.html never fails the deploy. */
 function indexHtmlWarning(files: ProcessedFile[]): string | null {
   const singleNonIndex = getSingleNonIndexHtmlFileName(files);
   if (singleNonIndex) {
@@ -142,12 +141,9 @@ function indexHtmlWarning(files: ProcessedFile[]): string | null {
 }
 
 /**
- * Best-effort local persistence of the anonymous claim handoff. Note this does
- * NOT reach the dashboard: localStorage is per-origin, so a token written here
- * (e.g. www.netlify.com) is invisible to app.netlify.com. The cross-origin
- * handoff is the URL fragment on the claim redirect; this only helps if the
- * drop and claim share an origin. Authenticated deploys never call this —
- * there is no claim token, and the upload bearer must never be persisted.
+ * Best-effort claim persistence. localStorage is per-origin, so this never
+ * reaches app.netlify.com — the URL fragment is the real cross-origin handoff.
+ * Authenticated deploys skip it: no claim token, and bearers are never persisted.
  */
 function persistAnonymousClaimLocally(token: string, siteName: string): void {
   try {
@@ -183,11 +179,7 @@ export function useDropDeploy({
   onError,
   track,
 }: UseDropDeployOptions) {
-  /**
-   * Typed veneer over the consumer's `track`: each payload is checked against
-   * the DROPZONE_EVENTS contract, so a renamed property fails to compile
-   * instead of silently forking the analytics history.
-   */
+  /** Typed veneer over `track` — a renamed property fails to compile instead of forking analytics history. */
   const emit = <E extends DropZoneEventName>(event: E, props: DropZoneEventProperties[E]) =>
     // The event interfaces carry no index signature, hence the cast to TrackFn's record.
     track(event, props as Record<string, unknown>);
@@ -220,10 +212,8 @@ export function useDropDeploy({
   const busy = status.kind !== 'idle' && status.kind !== 'error';
 
   /**
-   * Create a site and enqueue a build for an already-zipped drop. Returns
-   * `null` when the visitor turns out not to be logged in — nothing is created
-   * in that case, so the caller can still stash the archive and hand off to
-   * signup. Every other failure throws and is reported by the caller's `catch`.
+   * Site + build for a zipped drop. `null` = not logged in (nothing created,
+   * so the caller can still stash and hand off); other failures throw.
    */
   async function enqueueZippedBuild(
     client: BuildClient,
@@ -257,10 +247,8 @@ export function useDropDeploy({
   }
 
   /**
-   * `fileTypes` is the MIME types of the selection, read at the drop boundary
-   * (see `getFileTypes`) and passed in rather than derived here — it has to be
-   * captured before `read()` runs so it survives a read that throws. Omitted
-   * from events when empty rather than sent as `[]`.
+   * `fileTypes` is captured at the drop boundary, before `read()` runs, so it
+   * survives a read that throws. Omitted from events when empty, never `[]`.
    */
   async function deploy(
     read: () => Promise<ProcessedFile[]>,
@@ -272,12 +260,8 @@ export function useDropDeploy({
 
     const typeProps = fileTypes.length ? { file_types: fileTypes } : {};
 
-    // Every failure path reports through here so the failure event stays
-    // uniform. `file_count` is only included where the file set is known (it
-    // isn't if `read()` threw); `file_types` always rides along because it *is*
-    // known then — a rejected single file is the main thing worth seeing.
-    // `reason` is raw (e.g. "drop failed: 429") for analytics; `message` is the
-    // humanized copy the user sees; `onError` gets both.
+    // Single failure funnel. `file_count` only when the file set is known;
+    // `reason` is raw for analytics, `message` is the humanized copy; `onError` gets both.
     const fail = (message: string, reason: string, extra?: Record<string, unknown>) => {
       setStatus({ kind: 'error', message });
       emit(DROPZONE_EVENTS.DEPLOY_FAILED, { method: source, reason, ...typeProps, ...extra });
@@ -285,10 +269,9 @@ export function useDropDeploy({
     };
 
     try {
-      // Auto-rename a lone non-index HTML file to index.html so it is served at
-      // the site root. Detection (getSingleNonIndexHtmlFileName) sits on the
-      // read side; recompute the warning on the renamed set so the fixable
-      // single-file case no longer warns and only the multi-HTML case does.
+      // Rename a lone non-index HTML file so it is served at the site root.
+      // Warnings are computed on the renamed set, so the fixable single-file
+      // case no longer warns and only the multi-HTML case does.
       const files = renameSingleNonIndexHtmlToIndex(await read());
       if (!files.length) {
         fail('No files found to deploy.', 'No files found to deploy.', { file_count: 0 });
@@ -319,12 +302,8 @@ export function useDropDeploy({
   }
 
   /**
-   * A drop that needs a build. Build-required projects can't deploy through the
-   * anonymous drop API — it only performs static deploys, so building one this
-   * way yields a broken site. They're routed to the authenticated build path
-   * instead, or stashed and handed off to signup when there is no session.
-   * Consumers can take over entirely with `onBuildRequired`, or own just the
-   * signup hand-off with `onBuildSignupHandoff`.
+   * Build-required drops can't use the anonymous API (static-only): build in
+   * the account, or stash + hand off to signup when there's no session.
    */
   async function handleBuildRequiredDrop(
     files: ProcessedFile[],
@@ -372,8 +351,7 @@ export function useDropDeploy({
 
       // No session after all (the auth hint cookie can outlive the session).
       // Nothing was created — stash the archive so the drop survives the
-      // signup round-trip. When the visitor is back on this origin
-      // authenticated, the mount-time resume deploys it for them.
+      // signup round-trip.
       stashed = await saveDropStash(archive.file, archive.buildSettings);
       if (stashed) {
         emit(DROPZONE_EVENTS.PROJECT_STASHED, {
@@ -387,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.
@@ -399,13 +389,9 @@ export function useDropDeploy({
   }
 
   /**
-   * Try the authenticated static deploy, or report that the visitor has no
-   * session. NotAuthenticatedError is the one failure that returns null and
-   * lets the caller fall back to the anonymous flow — it's thrown before
-   * anything is created (the auth hint cookie can outlive the session), so
-   * retrying anonymously can't strand a half-made site. Any later failure is
-   * real and rethrows: falling back then would leave an empty site in the
-   * account and deploy a duplicate.
+   * `null` = no session (pre-mutation, so the anonymous fallback is safe).
+   * Anything else rethrows — falling back after the site exists would strand
+   * an empty site and deploy a duplicate.
    */
   async function attemptAuthenticatedStaticDeploy(
     client: DropClient,
@@ -447,11 +433,10 @@ export function useDropDeploy({
     }
 
     setStatus({ kind: 'redirecting', target: authenticated ? 'dashboard' : 'claim' });
-    // Fired before the redirect below. Note: the navigation can cut a
-    // fire-and-forget analytics request short — see the docs for delivery
-    // hardening (sendBeacon / deferring the redirect). `auth_fallback` is only
-    // sent when an authenticated attempt bounced (stale auth hint) — omitted
-    // otherwise, like `file_types`.
+    // The redirect below can cut a fire-and-forget analytics request short;
+    // harden delivery with sendBeacon or by deferring the redirect.
+    // `auth_fallback` is only sent when an authenticated attempt bounced
+    // (stale auth hint) — omitted otherwise, like `file_types`.
     emit(DROPZONE_EVENTS.DEPLOY_SUCCEEDED, {
       method: source,
       site_name: result.subdomain,
@@ -471,7 +456,6 @@ export function useDropDeploy({
     redirectAfterStaticDeploy(authenticated, result.subdomain, token);
   }
 
-  /** Hand the visitor to their new site: its dashboard page, or the claim page. */
   function redirectAfterStaticDeploy(authenticated: boolean, siteName: string, token: string) {
     if (authenticated) {
       // The site already lives in the visitor's account — send them straight
@@ -486,13 +470,8 @@ export function useDropDeploy({
   }
 
   /**
-   * Deploy a drop stashed before the signup hand-off (see `buildStash`).
-   *
-   * The stash is consumed only once the visitor is provably authenticated —
-   * the marker (or the auth hint behind `getUploadToken`) can outlive the
-   * session, and consuming on a bounced attempt would quietly lose the drop.
-   * Once past that gate it is consumed whether the deploy succeeds or fails,
-   * so a broken project can never retry-loop.
+   * Deploy the stashed drop. Consumed only once provably authenticated (a
+   * bounced attempt keeps it), then consumed win or lose — no retry loops.
    */
   async function resumeStashedBuild(client: BuildClient) {
     const stash = await loadDropStash();
@@ -517,7 +496,7 @@ export function useDropDeploy({
 
     if (!built) {
       // Still no session — the visitor came back logged out. Keep the stash for
-      // their next authenticated visit and return to idle without fuss.
+      // their next authenticated visit.
       setStatus({ kind: 'idle' });
       return;
     }

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/analytics.ts

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