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

package/dist/drop-core/zip.d.ts

@@ -1,46 +1,23 @@
 import { InferredBuildSettings } from './detectBuild';
 import { ProcessedFile } from './types';
-/**
- * Render inferred settings as a `[build]` table. Only `command` and `publish`
- * are written: everything else (functions directory, plugins, node version)
- * is zero-config on Netlify's side and guessing at it would override detection
- * that is better informed than we are.
- */
+/** Renders a [build] table — command and publish only; everything else is zero-config server-side. */
 export declare function generateNetlifyToml({ command, publish }: InferredBuildSettings): string;
 export interface ZipOptions {
     /** Filename given to the produced `File`. Shows up as the build's source archive. */
     name?: string;
-    /**
-     * Synthesise a `netlify.toml` `[build]` table from `inferBuildSettings` when the
-     * drop doesn't declare one (default `true`). Set `false` to upload the files
-     * exactly as dropped and let buildbot resolve every setting itself.
-     */
+    /** Synthesise a [build] table when the drop lacks one (default true); false uploads as-dropped. */
     synthesizeNetlifyToml?: boolean;
 }
 export interface ZipResult {
     /** The archive, ready to hand to `createBuildFromZip`. */
     file: File;
-    /**
-     * The settings written into `netlify.toml`, or `null` when the archive is a
-     * faithful copy of the drop — either because it already declared a `[build]`
-     * table, or because nothing could be inferred with confidence.
-     */
+    /** Settings written into netlify.toml, or null when the archive is a faithful copy. */
     buildSettings: InferredBuildSettings | null;
 }
 /**
- * Zip an already-read file set into the source archive that
- * `POST /sites/{id}/builds` expects.
- *
- * The input is the same root-normalized `ProcessedFile[]` the static deploy path
- * uses (see `readFiles`), so junk — dotfiles, `node_modules`, macOS metadata — is
- * already gone and paths sit at the deploy root. Output directories (`dist/`,
- * `build/`) are deliberately *not* stripped: buildbot regenerates them when
- * there's a build command, and a drop whose `netlify.toml` publishes a committed
- * directory without a command would break if we removed it.
- *
- * When the drop needs a build but declares no `[build]` table, an inferred one is
- * written in (appended to an existing `netlify.toml`, or created if there is
- * none) so buildbot doesn't publish the project's source. See
- * `inferBuildSettings` for how conservative that inference is.
+ * Zip a read file set into the archive `POST /sites/{id}/builds` expects.
+ * Junk is already gone (readFiles); dist/build are deliberately kept — a drop
+ * publishing a committed directory without a command would break without them.
+ * A [build] table is synthesised when missing (appended, so redirects survive).
  */
 export declare function zipFiles(files: ProcessedFile[], { name, synthesizeNetlifyToml }?: ZipOptions): Promise<ZipResult>;

package/package.json

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

package/packages/components/preact/DropZone/DropZone.tsx

@@ -25,26 +25,13 @@ const DRAG_INACTIVE_MS = 120;
 
 const defaultClaimUrl = (siteName: string) => `https://app.netlify.com/drop/${siteName}`;
 
-/**
- * Where an authenticated static deploy lands: the new site's project overview,
- * the same place the app's own logged-in drop sends you.
- */
+/** The project overview — where the app's own logged-in drop lands too. */
 const defaultSiteDashboardUrl = (siteName: string) =>
   `https://app.netlify.com/projects/${siteName}`;
 
-/**
- * Where a build-required drop is sent by default. Mirrors the app's own Drop
- * page: signup with `next=/drop`, so after signup + email verification the user
- * lands back on the authenticated Drop page and can build there.
- */
+// Mirrors the app's own Drop page hand-off.
 const defaultBuildSignupUrl = 'https://app.netlify.com/signup?next=/drop&utm_campaign=drop';
 
-/**
- * Where an authenticated build drop lands: the new site's project overview —
- * the same destination as a static deploy, and where the app's own Drop page
- * sends build drops. The overview surfaces the in-progress deploy; consumers
- * who want the deploy-log page instead can override with `build.deployId`.
- */
 const defaultBuildDeployUrl = ({ siteName }: DeployedBuild) =>
   `https://app.netlify.com/projects/${siteName}`;
 
@@ -57,30 +44,17 @@ interface Props {
   client?: DropClient;
   /** Build the "claim this site" URL from the assigned site name (subdomain). */
   claimUrl?: (siteName: string) => string;
-  /**
-   * Where an authenticated static deploy sends the visitor — the site already
-   * lives in their account, so there is no claim step. Defaults to the new
-   * site's project overview on app.netlify.com.
-   */
+  /** Destination after an authenticated static deploy (no claim step). Default: the project overview. */
   siteDashboardUrl?: (siteName: string) => string;
   /**
-   * Where to send a build-required drop (framework source, build command,
-   * functions) that can't be built here — no `getUploadToken`/`buildClient`, or a
-   * visitor who isn't logged in. Such projects can't deploy through the anonymous
-   * static drop API, so by default the user is redirected here — the app signup
-   * page with `next=/drop` — to build on the authenticated Drop page. Override to
-   * point at your own destination.
+   * Signup hand-off for a build drop with no session. The drop is stashed on
+   * this origin first — return the visitor here and it deploys automatically.
    */
   buildSignupUrl?: string;
   /**
-   * Mint a short-lived bearer token for direct api.netlify.com uploads — pass it
-   * to switch on the whole authenticated path for logged-in visitors: static
-   * drops deploy straight into their account (then `siteDashboardUrl`), and
-   * build-required drops build in place instead of being handed off to the app.
-   * On netlify.com this reads `GET /access-control/generate-access-control-token`.
-   * Resolving `null` means "no session": static drops fall back to the anonymous
-   * claim flow, build drops to `buildSignupUrl`.
-   * See [Logged-in visitors](#logged-in-visitors).
+   * Mint the upload bearer — passing this switches on the whole authenticated
+   * path. `null` means "no session": static drops fall back to the anonymous
+   * claim flow; build drops stash and hand off. See the docs' Logged-in visitors.
    */
   getUploadToken?: () => Promise<string | null>;
   /**
@@ -88,108 +62,46 @@ interface Props {
    * Takes precedence over `getUploadToken` for the build path.
    */
   buildClient?: BuildClient;
-  /**
-   * Inject a custom authenticated `DropClient` for static drops (tests, staging,
-   * a different account flow). Takes precedence over `getUploadToken` for the
-   * static path. Distinct from `client`, which is the anonymous fallback.
-   */
+  /** Custom authenticated static-drop client; wins over `getUploadToken`. (`client` is the anonymous fallback.) */
   authenticatedDropClient?: DropClient;
-  /**
-   * API root for the authenticated paths' JSON calls, which go through your
-   * access-control rewrite so the session cookie authorizes them. Defaults to
-   * `/access-control/bb-api/api/v1`. (Uploads always go direct to
-   * `api.netlify.com` — the proxy can't carry bodies that large.)
-   */
+  /** Root for the session-cookie JSON calls, via your access-control rewrite. Uploads always go direct. */
   proxyBase?: string;
   /** Create the visitor's new project in this account. Omit for their default account. */
   accountSlug?: string;
-  /**
-   * Where an enqueued build sends the visitor. Defaults to the new site's
-   * project overview, same as a static deploy; `build.deployId` is available for
-   * consumers who want the deploy-log page instead.
-   */
+  /** Destination after a build is enqueued. Default: the project overview (`build.deployId` for the logs page). */
   buildDeployUrl?: (build: DeployedBuild) => string;
   /**
-   * Poll until the build finishes before handing off, instead of redirecting as
-   * soon as it's enqueued. The trade-off: waiting means a failing build surfaces
-   * its own error message here (via `onError` and the overlay) rather than the
-   * visitor discovering it on the deploy page — at the cost of holding them on a
-   * spinner for the length of the build, which is minutes. Off by default.
+   * Hold the visitor until the build finishes (off by default — builds take
+   * minutes). On is the only way a failing build's own message reaches `onError`.
    */
   waitForBuild?: boolean;
-  /**
-   * Called when a build-required drop is detected, instead of building it or
-   * redirecting. Use it to own the hand-off yourself (custom routing, persisting
-   * the drop, gating on auth). When set, the component neither builds nor
-   * redirects. The static drop path is unaffected either way.
-   */
+  /** Take over build-required drops entirely — when set, the component neither builds nor redirects. */
   onBuildRequired?: (info: BuildDetection) => void;
   /**
-   * Called instead of the `buildSignupUrl` redirect when a build-required drop
-   * can't be built here (no session). By this point the drop has been stashed
-   * on this origin (`stashed` says whether that succeeded) — own the hand-off
-   * however fits your auth flow, e.g. open a signup popup that keeps the
-   * visitor on the page. Once they're back authenticated, a remount of the
-   * zone deploys the stash automatically.
+   * Own the signup hand-off instead of the `buildSignupUrl` redirect (e.g. an
+   * auth popup). The drop is already stashed; a remount while authenticated
+   * deploys it.
    */
   onBuildSignupHandoff?: (info: { stashed: boolean; detection: BuildDetection }) => void;
-  /**
-   * Deploy a previously stashed build drop automatically when the zone mounts
-   * with an authenticated visitor (default `true`). The stash is written when a
-   * logged-out build drop is handed to signup; see
-   * [Signup hand-off and auto-resume](#signup-hand-off-and-auto-resume).
-   */
+  /** Auto-deploy a stashed build drop on mount when authenticated (default true). */
   resumeStashedBuilds?: boolean;
   /** Called once the deploy is live. */
   onDeploy?: (result: DeployedSite) => void;
-  /**
-   * Called once a build-required drop has been zipped, uploaded and enqueued —
-   * before the redirect to `buildDeployUrl`. The site exists at this point but
-   * won't serve content until the build finishes.
-   */
+  /** Called once a build is enqueued, before the `buildDeployUrl` redirect. */
   onBuildDeploy?: (build: DeployedBuild) => void;
-  /**
-   * Called when a deploy fails, with a humanized `message` (ready to show a
-   * user — the same copy the built-in overlay uses) and the raw `reason`. Pair
-   * this with `showStatus={false}` to render your own error UI.
-   */
+  /** Deploy failures: humanized `message` (the overlay's copy) + raw `reason`. Pair with showStatus={false}. */
   onError?: (error: DeployError) => void;
   /**
-   * Render the built-in status overlay (drag tint, spinner, progress bar, error).
-   * Set to `false` to suppress it entirely and keep your children visible, then
-   * drive your own feedback from the `data-state` attribute on the root element.
-   * Note: in this mode you're responsible for surfacing errors yourself — use
-   * `onError` to get the message.
+   * Render the built-in overlay. `false` keeps children visible — drive your
+   * own feedback from `data-state`, and surface errors yourself via `onError`.
    */
   showStatus?: boolean;
   /**
-   * Analytics hook. Called at each tracked moment with an event name and
-   * properties. Stays provider-agnostic — wire it to Segment/Amplitude/GA in the
-   * consuming app, e.g. `onTrack={(name, props) => new Analytics().track(name, props)}`.
-   * Emitted events (all include `dropzone_id` when `analyticsId` is set):
-   * - `dropzone_files_dropped`  — files dropped via drag  ({ method: 'drag', file_count, file_types })
-   * - `dropzone_browse_opened`  — file picker opened       ({ method: 'keyboard' | 'click' })
-   * - `dropzone_build_required` — drop needs a build (built here, or handed off) ({ method, reason, file_count, file_types })
-   * - `dropzone_deploy_succeeded` — static deploy went live ({ method, site_name, file_count, authenticated, auth_fallback?, file_types })
-   * - `dropzone_build_deploy_succeeded` — build enqueued for a logged-in visitor ({ method, reason, site_name, file_count, framework?, file_types })
-   * - `dropzone_deploy_failed`  — deploy or build errored out ({ method, reason, file_count?, file_types })
-   *
-   * `authenticated` says whether the deploy landed in the visitor's account;
-   * `auth_fallback: true` is sent only when an authenticated attempt bounced
-   * (stale auth hint) and the drop completed anonymously — omitted otherwise.
-   * `file_types` is the sorted, de-duplicated list of MIME types in the
-   * selection, with `application/octet-stream` standing in wherever the browser
-   * reports none (a dragged folder, an `.exe`). It is omitted when the browser
-   * exposes no files at all. Note `dropzone_files_dropped` only fires for drag —
-   * a file-picker selection reports its types on the outcome events, as
-   * `dropzone_browse_opened` fires before any file exists.
+   * Provider-agnostic analytics hook. Event names and payload shapes live in
+   * DROPZONE_EVENTS / DropZoneEventProperties (drop-core/analytics.ts).
    */
   onTrack?: TrackFn;
-  /**
-   * Stable identifier for this instance, attached to every tracked event as
-   * `dropzone_id`. Set it when a page renders more than one Drop Zone so the
-   * events can be told apart in Amplitude.
-   */
+  /** Stamped on every event as `dropzone_id` — set when a page has more than one zone. */
   analyticsId?: string;
   className?: string;
 }
@@ -219,8 +131,6 @@ export default function DropZone({
   analyticsId,
   className,
 }: Props) {
-  // Tag every event with this instance's id so multiple zones on a page can be
-  // told apart, then hand it off to the consumer's analytics.
   const track: TrackFn = (event, properties = {}) =>
     onTrack?.(event, analyticsId ? { dropzone_id: analyticsId, ...properties } : properties);
 
@@ -254,8 +164,6 @@ export default function DropZone({
     inputRef.current?.click();
   };
 
-  // The overlay only paints when there's something to show — dragging, deploying,
-  // or an error. With `showStatus` off, the consumer drives their own feedback.
   const showOverlay = showStatus && (active || busy || status.kind === 'error');
   const rootClass = [
     'n-dropzone',
@@ -344,11 +252,8 @@ export default function DropZone({
 }
 
 /**
- * Track whether a drag is currently over the zone. A drag has no reliable
- * "cancelled" event — pressing Escape or dropping elsewhere just stops the
- * stream of `dragover` events — so we stay active only while they keep arriving
- * and clear shortly after they stop. This also handles drags over children,
- * where `dragleave` targets a child rather than the zone.
+ * Drag-over tracking by dragover decay: drags have no reliable cancel event,
+ * and dragleave targets children — so stay active while events keep arriving.
  */
 function useDragActive() {
   const [active, setActive] = useState(false);

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

@@ -15,7 +15,7 @@ import {
   getSingleNonIndexHtmlFileName,
   hasMultipleHtmlFilesWithoutIndex,
   humanizeDropError,
-  NotAuthenticatedError,
+  isNotAuthenticatedError,
   renameSingleNonIndexHtmlToIndex,
   type BuildClient,
   type BuildDetection,
@@ -88,7 +88,6 @@ export type DeployStatus =
   | { kind: 'redirecting'; target: 'claim' | 'dashboard' | 'signup' | 'build' }
   | { kind: 'error'; message: string };
 
-/** Re-exported from the drop-core analytics contract, where the shape now lives. */
 export type { TrackFn };
 
 interface UseDropDeployOptions {
@@ -113,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':
@@ -130,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) {
@@ -143,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 {
@@ -184,16 +179,9 @@ export function useDropDeploy({
   onError,
   track,
 }: UseDropDeployOptions) {
-  /**
-   * Typed veneer over the consumer's `track`: event names come from the
-   * DROPZONE_EVENTS contract and each payload is checked against its shape,
-   * 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 cast bridges to TrackFn's loose record: the interfaces have no index
-    // signature (so payloads stay closed for consumers), and the checking that
-    // matters happened against DropZoneEventProperties[E] above.
+    // The event interfaces carry no index signature, hence the cast to TrackFn's record.
     track(event, props as Record<string, unknown>);
 
   const [status, setStatus] = useState<DeployStatus>({ kind: 'idle' });
@@ -224,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,
@@ -247,7 +233,7 @@ export function useDropDeploy({
         buildSettings,
       };
     } catch (err) {
-      if (err instanceof NotAuthenticatedError) return null;
+      if (isNotAuthenticatedError(err)) return null;
       throw err;
     }
   }
@@ -261,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[]>,
@@ -276,17 +260,8 @@ export function useDropDeploy({
 
     const typeProps = fileTypes.length ? { file_types: fileTypes } : {};
 
-    // Surface a failure: move to the error state and emit the matching
-    // analytics event. Centralised so every failure path (empty selection, a
-    // read/deploy throw) reports uniformly — the mirror of the
-    // `dropzone_deploy_succeeded` event on the happy path. `file_count` is only
-    // included where the file set is known (it isn't if `read()` itself threw);
-    // `file_types` rides along on every failure precisely because it *is* known
-    // in that case — a rejected single file is the main thing we want to see.
-    // `reason` goes to analytics as-is (raw, e.g. "drop failed: 429"); `message`
-    // is what the user sees, which for a caught error is humanized separately.
-    // `onError` gets both so a consumer (e.g. with `showStatus={false}`) can show
-    // the humanized message while keeping the raw reason for their own logging.
+    // 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 });
@@ -294,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 });
@@ -328,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[],
@@ -381,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, {
@@ -408,13 +377,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,
@@ -425,7 +390,7 @@ export function useDropDeploy({
         onProgress: e => setStatus(progressToStatus(e)),
       });
     } catch (err) {
-      if (err instanceof NotAuthenticatedError) return null;
+      if (isNotAuthenticatedError(err)) return null;
       throw err;
     }
   }
@@ -456,11 +421,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,
@@ -480,7 +444,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
@@ -495,13 +458,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();
@@ -526,7 +484,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

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