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

package/packages/drop-core/buildClient.ts

@@ -5,19 +5,13 @@ import {
   DEFAULT_PROXY_BASE,
   DEFAULT_TIMEOUT_MS,
 } from './constants';
-import {
-  BuildCreateError,
-  BuildFailedError,
-  BuildTimeoutError,
-  NotAuthenticatedError,
-} from './errors';
+import { BuildCreateError, BuildFailedError, BuildTimeoutError } from './errors';
 import type { BuildSite } from './types';
 
 export type { BuildSite } from './types';
 
 /** The subset of a Netlify Build returned by `POST /sites/{id}/builds`. */
 export interface BuildResponse {
-  /** build id */
   id: string;
   /** the deploy the build produces — present as soon as the build is enqueued */
   deploy_id?: string;
@@ -30,28 +24,14 @@ export interface BuildClient {
 }
 
 export interface AuthenticatedBuildClientConfig {
-  /**
-   * Base for JSON API calls, routed through the consumer's access-control
-   * rewrite so the session cookie authenticates them. On netlify.com that
-   * rewrite is `/access-control/*` → the app's access-control function, which
-   * makes `/access-control/bb-api/api/v1` the API root (the default here).
-   */
+  /** Root for session-cookie JSON calls, via the consumer's access-control rewrite. */
   proxyBase?: string;
-  /**
-   * Direct API base for the zip upload. The proxy above runs in a Lambda with a
-   * ~6MB request body limit, so the multipart POST has to go straight to
-   * `api.netlify.com` (whose `/api/*` CORS policy allows any origin).
-   */
+  /** Direct base for the zip upload — the proxy's ~6MB Lambda body limit can't carry it. */
   apiBase?: string;
   /**
-   * Mint a bearer token for that direct upload. On netlify.com this is
-   * `GET /access-control/generate-access-control-token`, whose
-   * `accessControlToken` the API decrypts back into the user's access token.
-   * Resolving `null` means "no session" and surfaces as `NotAuthenticatedError`.
-   *
-   * Note the token issued to a non-app origin lives only 30 seconds. It is
-   * minted immediately before the upload, but a zip that takes longer than that
-   * to transfer will still be rejected mid-flight — see `createBuildFromZip`.
+   * Mint the upload bearer; `null` means "no session". Non-app origins get
+   * 30-second tokens — a zip slower than that fails mid-flight (see
+   * `createBuildFromZip`).
    */
   getUploadToken: () => Promise<string | null>;
   /** Create the site in this account. Omit to use the user's default account. */
@@ -65,16 +45,9 @@ export interface AuthenticatedBuildClientConfig {
 }
 
 /**
- * Authenticated drop client for projects that need a build. Unlike
- * `AnonymousDropClient` — which creates an account-less static site and can only
- * upload pre-built files — this creates a real site in the user's account and
- * hands buildbot a source archive to build, mirroring what app.netlify.com does
- * for a drag-and-drop build.
- *
- * Requests split across two hosts by necessity: JSON calls go through the
- * consumer's access-control proxy (cookie session, no token handling in the
- * browser), while the zip upload goes direct to `api.netlify.com` with a
- * short-lived bearer token because the proxy can't carry a body that large.
+ * Builds a drop in a logged-in visitor's account: create the site, hand
+ * buildbot the source zip. JSON rides the cookie proxy; the zip goes direct
+ * with a bearer (the proxy can't carry it).
  */
 export class AuthenticatedBuildClient implements BuildClient {
   private proxyBase: string;
@@ -103,29 +76,24 @@ export class AuthenticatedBuildClient implements BuildClient {
     this.timeoutMs = timeoutMs;
   }
 
-  /**
-   * Create the site the build deploys into. A logged-out visitor fails here,
-   * before anything is created — see `createSiteInAccount` for the error
-   * mapping that makes the signup fallback safe.
-   */
+  /** A logged-out visitor fails here, before anything is created (see `createSiteInAccount`). */
   async createSite(): Promise<BuildSite> {
     return createSiteInAccount(this.proxyBase, this.accountSlug);
   }
 
   /**
-   * Upload the source archive and enqueue a build. Direct to `api.netlify.com`
-   * (see the note on `apiBase`), authorized by a freshly minted bearer token.
-   * `Content-Type` is left unset on purpose so the browser adds the multipart
-   * boundary itself.
+   * One multipart request on a fresh 30s bearer — a slower zip fails mid-flight
+   * (the app origin gets 300s; raising ours is a platform-side change).
+   * Content-Type stays unset so the browser adds the multipart boundary.
    *
-   * Known ceiling: this is one request on a 30s token, and re-minting can't
-   * help once it is in flight. A zip that takes longer than that to upload will
-   * fail — the app origin gets 300s for exactly this reason, and lifting the
-   * limit for other origins is a platform-side change.
+   * Never NotAuthenticatedError, including for a 401: the site exists by the
+   * time this runs, so signalling "no session" would strand it and re-stash
+   * the drop for the next visit to strand another. `createSite` is the auth
+   * gate for this path.
    */
   async createBuildFromZip(siteId: string, zip: File): Promise<BuildResponse> {
     const token = await this.getUploadToken();
-    if (!token) throw new NotAuthenticatedError();
+    if (!token) throw new BuildCreateError();
 
     const body = new FormData();
     body.append('zip', zip);
@@ -136,22 +104,14 @@ export class AuthenticatedBuildClient implements BuildClient {
       headers: { Authorization: `Bearer ${token}` },
       body,
     });
-    if (res.status === 401 || res.status === 403) throw new NotAuthenticatedError();
     if (!res.ok) throw new BuildCreateError(res.status);
     return res.json();
   }
 
   /**
-   * Poll the build's deploy until it settles, mirroring
-   * `AnonymousDropClient.waitUntilReady` — resolve on `ready`, throw on
-   * `error`/`rejected`, throw on timeout. A build that hasn't been given a
-   * deploy id yet has nothing pollable, so it resolves immediately and the
-   * caller falls back to the site page.
-   *
-   * Optional in the drop flow, and off by default: a build takes minutes, so
-   * the useful hand-off is usually the project page rather than a spinner.
-   * Polling rides the session cookie, so it cannot outlive its credentials the
-   * way a 30s bearer would.
+   * Optional (a build takes minutes; the useful hand-off is the project page).
+   * Polls on the cookie, so it can't outlive its credentials; no deploy id yet
+   * means nothing pollable, so it resolves immediately.
    */
   async waitUntilBuildReady(build: BuildResponse): Promise<void> {
     if (!build.deploy_id) return;
@@ -163,8 +123,6 @@ export class AuthenticatedBuildClient implements BuildClient {
       timeoutMs: this.timeoutMs,
     });
     if (settled.outcome === 'ready') return;
-    // The build's own error message is the only actionable part of a failure,
-    // so it travels on the typed error rather than being flattened away.
     if (settled.outcome === 'failed') throw new BuildFailedError(settled.errorMessage);
     throw new BuildTimeoutError();
   }

package/packages/drop-core/buildStash.ts

@@ -1,21 +1,11 @@
 import type { InferredBuildSettings } from './detectBuild';
 
 /**
- * Carry a build-required drop across the signup round-trip.
- *
- * A logged-out visitor's drop can't be built (builds have no anonymous
- * equivalent), so before handing them to signup the zone stashes the source
- * archive here — IndexedDB, because the zip is far beyond localStorage's
- * budget. When they return to this origin authenticated, the zone deploys the
- * stash automatically instead of asking them to drop again.
- *
- * Storage is per-origin: a stash written on www.netlify.com can only ever be
- * resumed on www.netlify.com. That is the design, not a limitation — it is
- * exactly why the hand-off page must bring the visitor back here.
- *
- * Every operation is failure-swallowing: the stash is an enhancement, and a
- * browser without IndexedDB (or with a full quota) degrades to the plain
- * signup redirect the zone always supported.
+ * Carries a build drop across the signup round-trip: stash the zip in
+ * IndexedDB before the hand-off, deploy it when the visitor returns
+ * authenticated. Storage is per-origin by design — the hand-off must bring
+ * them back here. Every operation swallows failures: no storage means the
+ * plain signup redirect the zone always supported.
  */
 
 export interface DropBuildStash {
@@ -92,11 +82,7 @@ const clearMarker = () => {
   localStorage.removeItem(MARKER_KEY);
 };
 
-/**
- * Stash a drop's source archive for an automatic deploy after signup. Returns
- * whether it was actually stored — callers use that only to phrase the
- * hand-off, never to block it.
- */
+/** Stash the archive for auto-deploy after signup. The result phrases the hand-off, never blocks it. */
 export async function saveDropStash(
   zipFile: File,
   buildSettings: InferredBuildSettings | null = null
@@ -139,11 +125,9 @@ export async function loadDropStash(): Promise<DropBuildStash | null> {
 }
 
 /**
- * The archive back out of storage as a real `File`. Structured clone should
- * preserve File identity, but implementations vary in whether the name and
- * prototype survive — and the build upload needs both (the multipart field is
- * named by the File). A Blob-shaped survivor is rewrapped; anything else is
- * treated as a corrupt record.
+ * Rewraps a Blob-shaped survivor into a named File — structured-clone
+ * implementations vary in preserving File identity, and the multipart upload
+ * needs the name. Anything less Blob-shaped is a corrupt record.
  */
 function rehydrateZipFile(stored: unknown): File | null {
   if (stored instanceof File && stored.name) return stored;

package/packages/drop-core/client.ts

@@ -1,9 +1,6 @@
 /**
- * The `DropClient` seam: the four calls a static deploy needs — mint a token,
- * create the deploy, upload a file, wait until ready — behind one interface,
- * so `deployFiles` runs the same pipeline whether the deploy is anonymous
- * (this file's `AnonymousDropClient`, claimed later by the visitor) or lands
- * directly in an account (`authedDropClient.ts`).
+ * The DropClient seam: the four calls a static deploy needs, behind one
+ * interface, so `deployFiles` runs the same pipeline anonymous or authenticated.
  */
 import { DEFAULT_API_BASE, DEFAULT_POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from './constants';
 import { DeployTimeoutError } from './errors';
@@ -23,7 +20,7 @@ export interface DropClient {
 
 /**
  * Unauthenticated drop client. Authorized server-side by the Referer header,
- * so it only works from an allowlisted origin (see backend checklist).
+ * so it only works from an allowlisted origin.
  */
 export class AnonymousDropClient implements DropClient {
   constructor(
@@ -64,10 +61,9 @@ export class AnonymousDropClient implements DropClient {
   }
 
   async waitUntilReady(deploy: DropResponse, token: string): Promise<void> {
-    // Poll the deploy with the drop token until ready.
-    // Note: `/deploys/{id}` expects the deploy_id (BSON), not the site id (UUID)
-    // that lives at `deploy.id`. See drop_controller.rb; Deploy.find(uuid) is nil
-    // and the request 401s misleadingly via require_current_actor!.
+    // `/deploys/{id}` expects the deploy_id (BSON), not the site id (UUID) that
+    // lives at `deploy.id`. See drop_controller.rb; Deploy.find(uuid) is nil and
+    // the request 401s misleadingly via require_current_actor!.
     const deadline = this.timeoutMs / this.pollIntervalMs;
     for (let i = 0; i < deadline; i++) {
       const res = await fetch(`${this.apiBase}/deploys/${deploy.deploy_id}`, {

package/packages/drop-core/constants.ts

@@ -1,15 +1,7 @@
-/**
- * The tunables shared across drop-core, one place and one comment each.
- * Module-specific constants (e.g. buildStash's storage caps) stay with their
- * module; anything two modules read belongs here.
- */
+/** Tunables shared across drop-core. Module-specific constants stay with their module. */
 
-/**
- * Root for session-cookie JSON calls, via the consumer's access-control
- * rewrite. On netlify.com, `/access-control/*` targets the app's
- * access-control function; the paths an origin may call are allowlisted
- * server-side.
- */
+// Root for session-cookie JSON calls via the consumer's access-control rewrite
+// (paths per origin are allowlisted server-side)
 export const DEFAULT_PROXY_BASE = '/access-control/bb-api/api/v1';
 
 /** Direct api.netlify.com root for the uploads the proxy's ~6MB Lambda body limit can't carry. */
@@ -24,16 +16,10 @@ export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 // Concurrent file uploads (matches netlify-cli's deploy engine)
 export const MAX_CONCURRENT_UPLOADS = 5;
 
-/**
- * How long a minted upload token is reused before minting another: 20 seconds.
- * The server issues non-app origins a 30s token; the gap leaves margin for the
- * request the token authorizes to finish.
- */
+// Reuse window for a minted upload token: 20s (server TTL is 30s; the gap is
+// margin for the request it authorizes to finish)
 export const TOKEN_REUSE_MS = 20 * 1000;
 
-/**
- * Waits between attempts of a failed file upload, as data so the whole curve
- * can be overridden (the tus-js-client `retryDelays` idiom). Three retries,
- * linear backoff; 400/422 responses never retry — see `uploadWithRetry`.
- */
+// Waits between upload retries, as data so the curve is overridable.
+// 400/422 never retry — see uploadWithRetry.
 export const UPLOAD_RETRY_DELAYS_MS: readonly number[] = [1_000, 2_000, 3_000];

package/packages/drop-core/deploy.ts

@@ -9,11 +9,7 @@ import { zipFiles, type ZipResult } from './zip';
 /** Responses that mean the request itself is wrong — retrying can only repeat the answer. */
 const NON_RETRIABLE_STATUSES = new Set([400, 422]);
 
-/**
- * Upload one file, retrying transient failures (5xx, 429, network errors) on
- * the given delay curve. A single flaky PUT among hundreds shouldn't kill the
- * whole deploy — every deploy client we know of retries here.
- */
+/** Retries transient failures (5xx/429/network) — one flaky PUT shouldn't kill the deploy. */
 async function uploadWithRetry(
   client: DropClient,
   deployId: string,
@@ -96,7 +92,6 @@ export async function deployFiles(
 }
 
 export interface BuildDeployResult {
-  /** The site created for this build. */
   site: BuildSite;
   /** The enqueued build; `deploy_id` is what the app's deploy page keys off. */
   build: BuildResponse;
@@ -108,22 +103,15 @@ export interface BuildDeployResult {
 
 export interface BuildDeployOptions extends DeployOptions {
   /**
-   * Poll until the build finishes instead of returning as soon as it's enqueued.
-   * Off by default: a build takes minutes, so the useful hand-off is usually the
-   * app's deploy page with its live logs, not a spinner. Turn it on when the
-   * caller needs to know the outcome — only then can a `BuildFailedError` reach
-   * it with the build's own error message.
+   * Wait for the build instead of returning at enqueue. Off by default (builds
+   * take minutes); on is the only way a BuildFailedError reaches the caller.
    */
   waitForBuild?: boolean;
 }
 
 /**
- * The build counterpart to `deployFiles`: zip the drop, create a site in the
- * user's account, and hand the archive to buildbot. Requires an authenticated
- * client — builds have no anonymous equivalent.
- *
- * Site creation deliberately happens *after* zipping, so a zip that fails
- * doesn't leave an empty site behind in the user's account.
+ * Zip the drop, create a site, hand buildbot the archive. Zipping comes first
+ * on purpose: a failed zip must not leave an empty site behind.
  */
 export async function deployBuild(
   client: BuildClient,
@@ -138,11 +126,7 @@ export async function deployBuild(
   return deployZippedBuild(client, archive, opts);
 }
 
-/**
- * Deploy an archive that was already zipped — the resume path for a drop
- * stashed across the signup round-trip (see `buildStash`), where `source.zip`
- * and its synthesised settings were produced before the visitor left.
- */
+/** Deploy an already-zipped archive — the resume path for a stashed drop (see `buildStash`). */
 export async function deployZippedBuild(
   client: BuildClient,
   { file: zip, buildSettings }: ZipResult,

package/packages/drop-core/detectBuild.ts

@@ -8,23 +8,16 @@ export type BuildReason =
   | 'functions-directory';
 
 export interface BuildDetection {
-  /** True when the dropped project needs a build step and can't be served as static files. */
+  /** The drop can't be served as static files. */
   buildRequired: boolean;
   /** The signal that decided it (first match wins), or null for a plain static drop. */
   reason: BuildReason | null;
 }
 
 /**
- * Dependencies whose presence implies a build even without an explicit `build`
- * script (e.g. a framework wired through its own CLI). Not exhaustive — the
- * `build` script check below catches the common case; this is the backstop.
- *
- * The value is the framework's default publish directory, or `null` where that
- * directory isn't a fixed string we can state with confidence — Nuxt, SvelteKit,
- * Remix and Angular all resolve it from an adapter or project name. `null` means
- * "a build is required, but don't guess a publish directory": see
- * `inferBuildSettings`, which only synthesises a `netlify.toml` when it knows
- * both halves of the answer.
+ * Frameworks that imply a build even without a `build` script, mapped to their
+ * default publish dir — `null` where it isn't a fixed string (Nuxt, SvelteKit,
+ * Remix, Angular resolve theirs), meaning "build required, don't guess".
  */
 const FRAMEWORK_DEPENDENCIES = new Map<string, string | null>([
   ['astro', 'dist'],
@@ -49,11 +42,7 @@ const FRAMEWORK_DEPENDENCIES = new Map<string, string | null>([
   ['@solidjs/start', null],
 ]);
 
-/**
- * A `netlify.toml` build config: a bare `[build]` table or any of its
- * sub-tables (`[build.environment]`, `[build.processing]`, …). Anchored to the
- * line start so a `[build]` mention inside a string/comment doesn't count.
- */
+// A [build] table or sub-table, line-anchored so a mention in a comment doesn't count.
 const NETLIFY_TOML_BUILD_SECTION = /^\s*\[build(\.[\w-]+)?\]/m;
 
 /** Zero-config functions directories — their presence alone requires bundling. */
@@ -61,7 +50,7 @@ const FUNCTIONS_DIR_PREFIXES = ['/netlify/functions/', '/netlify/edge-functions/
 
 const decoder = new TextDecoder();
 
-/** Find a file at the deploy root by its normalized path (leading slash). */
+/** Root paths are normalized with a leading slash. */
 function rootFile(files: ProcessedFile[], path: string): ProcessedFile | undefined {
   return files.find(f => f.path === path);
 }
@@ -90,23 +79,14 @@ function findFrameworkDependency(pkg: Record<string, unknown>): string | null {
   return null;
 }
 
-/** True if any dependency (prod or dev) is a known build-requiring framework. */
 function hasFrameworkDependency(pkg: Record<string, unknown>): boolean {
   return findFrameworkDependency(pkg) !== null;
 }
 
 /**
- * Decide whether a dropped project needs a build. Runs on the already-read,
- * root-normalized `ProcessedFile[]` (a dropped `.zip` is expanded and the common
- * root folder stripped upstream in `readFiles`), so build config sits at the
- * deploy root, e.g. `/netlify.toml`, `/package.json`.
- *
- * The anonymous drop API only performs static deploys, so a build-required
- * project can't go through it — the consumer redirects such drops to the
- * authenticated Drop page instead. This heuristic is deliberately lightweight
- * (no framework-detection dependency): it reads the two config files and looks
- * for the zero-config functions directories. A plain static site (HTML/CSS/JS,
- * no build config) returns `{ buildRequired: false }`.
+ * Does this drop need a build? Deliberately lightweight (two config files +
+ * the functions dirs; no framework-detection dependency). Input is
+ * root-normalized by `readFiles`, so config sits at `/netlify.toml` etc.
  */
 export function detectBuild(files: ProcessedFile[]): BuildDetection {
   const toml = rootFile(files, '/netlify.toml');
@@ -165,13 +145,8 @@ const LOCKFILE_PACKAGE_MANAGERS: ReadonlyArray<readonly [string, string]> = [
   ['/package-lock.json', 'npm'],
 ];
 
-/**
- * A bare `[build]` table header at the start of a line. Stricter than
- * `NETLIFY_TOML_BUILD_SECTION` on purpose: a config with only
- * `[build.environment]` carries no command or publish directory, so it still
- * needs a `[build]` table synthesised. (TOML permits defining a super-table
- * after its sub-tables, so appending one is valid.)
- */
+// Bare [build] only — stricter than the detection regex, since a config with
+// just [build.environment] still needs a [build] table synthesised.
 const NETLIFY_TOML_BUILD_TABLE = /^\s*\[build\]/m;
 
 function detectPackageManager(files: ProcessedFile[]): string {
@@ -182,20 +157,10 @@ function detectPackageManager(files: ProcessedFile[]): string {
 }
 
 /**
- * Infer the build command and publish directory for a build-required drop, so
- * `zipFiles` can write them into a `netlify.toml` that buildbot reads.
- *
- * Deliberately conservative: it returns settings **only** when both halves are
- * known — a `build` script (which gives the command) and a recognised framework
- * with a fixed default publish directory (which gives the output). Anything else
- * returns `null`, leaving the zip without a synthesised `[build]` table so
- * buildbot's own framework detection resolves the settings instead. That matters
- * because a `[build]` table with a command but no `publish` makes buildbot
- * publish the deploy root — shipping the project's *source* rather than its
- * built output, which is worse than not guessing at all.
- *
- * Returns `null` too when the drop already declares a `[build]` table: the
- * author's own config always wins.
+ * Build settings for the synthesised netlify.toml — only when BOTH halves are
+ * known (build script → command, known framework → publish). Guessing publish
+ * wrong ships source instead of output, so `null` beats a bad guess. An
+ * author-declared [build] table always wins (also `null`).
  */
 export function inferBuildSettings(files: ProcessedFile[]): InferredBuildSettings | null {
   const toml = rootFile(files, '/netlify.toml');

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

@@ -76,7 +76,9 @@ describe('humanizeDropError', () => {
     expect(humanizeDropError(new DeployFailedError('no index.html'))).toBe(
       'Your deploy failed: no index.html'
     );
-    expect(humanizeDropError(new DeployFailedError())).toBe('Your deploy failed. Please try again.');
+    expect(humanizeDropError(new DeployFailedError())).toBe(
+      'Your deploy failed. Please try again.'
+    );
   });
 
   it('reads a fetch TypeError as a connectivity problem', () => {

package/packages/drop-core/errors.ts

@@ -1,9 +1,6 @@
 /**
- * Thrown when the user drops or picks a single loose file that Drop can't turn
- * into a site on its own — anything that isn't a `.zip` (a site archive) or an
- * HTML page (served as index.html). A folder, multiple files, a zip, or a lone
- * HTML file are all fine; any other single file is rejected rather than
- * deployed as a one-asset site (matches react-ui).
+ * A single loose file that can't stand up a site — only a zip, folder,
+ * multiple files, or a lone HTML page may deploy (matches react-ui).
  */
 export class UnsupportedDropError extends Error {
   readonly code = 'unsupported-drop';
@@ -15,12 +12,8 @@ export class UnsupportedDropError extends Error {
 }
 
 /**
- * Thrown when an authenticated path (static or build) turns out to have no
- * usable session — the short-lived upload token came back empty, or the
- * session-cookie site create was refused, so nothing was created. For static
- * drops the flow falls back to the anonymous drop + claim; builds have no
- * anonymous equivalent, so the consumer's only recourse is to send the visitor
- * through login/signup and have them drop again.
+ * The pre-mutation "no session" signal: nothing was created yet, so static
+ * drops may fall back to the anonymous flow and build drops stash + hand off.
  */
 export class NotAuthenticatedError extends Error {
   readonly code = 'not-authenticated';
@@ -32,12 +25,8 @@ export class NotAuthenticatedError extends Error {
 }
 
 /**
- * Whether an error is the pre-mutation "no session" signal, however it
- * traveled. This package ships as both raw TypeScript (`./components`) and
- * compiled dist (`./preact`, `./drop-core`), so two copies of the class can
- * coexist in one app and defeat `instanceof` — the `code` brand is the
- * copy-proof fallback. Control flow that decides whether an anonymous retry
- * is safe must use this, never a bare `instanceof`.
+ * Copy-proof check for the "no session" error — `instanceof` misses class
+ * copies from the package's other entrypoint. Fallback gates must use this.
  */
 export function isNotAuthenticatedError(err: unknown): err is NotAuthenticatedError {
   if (err instanceof NotAuthenticatedError) return true;
@@ -71,12 +60,7 @@ export class BuildCreateError extends Error {
   }
 }
 
-/**
- * The build ran and ended in `error`/`rejected`. `reason` is the API's
- * `error_message` when there is one — it's the only part of a build failure that
- * says anything actionable (a failing build command, a missing dependency), so
- * it is surfaced to the user rather than swallowed.
- */
+/** The build ran and broke. `reason` carries the API's `error_message` — the only actionable part. */
 export class BuildFailedError extends Error {
   readonly code = 'build-failed';
 
@@ -96,10 +80,7 @@ export class BuildTimeoutError extends Error {
   }
 }
 
-/**
- * A static deploy ran and ended in `error`/`rejected`. Like a build failure,
- * the API's `error_message` is the actionable part, so it travels on the error.
- */
+/** A static deploy ran and ended in `error`/`rejected`; `reason` carries the API's `error_message`. */
 export class DeployFailedError extends Error {
   readonly code = 'deploy-failed';
 
@@ -152,9 +133,7 @@ export function humanizeDropError(err: unknown): string {
   }
   if (code === 'deploy-failed') {
     const reason = (err as DeployFailedError).reason;
-    return reason
-      ? `Your deploy failed: ${reason}`
-      : 'Your deploy failed. Please try again.';
+    return reason ? `Your deploy failed: ${reason}` : 'Your deploy failed. Please try again.';
   }
 
   if (code === 'build-timeout') {

package/packages/drop-core/fileTypes.ts

@@ -1,28 +1,14 @@
 /** What we report when the browser gives us no MIME type at all. */
 const UNKNOWN_TYPE = 'application/octet-stream';
 
-/**
- * Distinct types kept per event. Deduplication alone keeps this small for a real
- * site (a handful of types across hundreds of files); the cap is a backstop so an
- * unusual folder can't push an oversized property into the analytics payload.
- */
+// Cap on distinct types per event — a backstop against oversized analytics payloads.
 const MAX_TYPES = 20;
 
 /**
- * Distinct MIME types across a drop or file-picker selection, sorted so the same
- * selection always yields the same array.
- *
- * Read from the raw `File.type` at the drop boundary rather than from
- * `ProcessedFile`s: the MIME type only exists on the original `File`, and reading
- * can throw before any `ProcessedFile` does (an unsupported single file) — the
- * very case the file type is most worth knowing about.
- *
- * Browsers leave `File.type` empty for anything they don't recognise — a dragged
- * folder, an `.exe`, an extensionless file — so those collapse to
- * `application/octet-stream` and the property never carries an empty string.
- *
- * Call this synchronously inside the drop handler: a `DataTransfer` detaches once
- * the event turn ends.
+ * Distinct, sorted MIME types of a selection. Read at the drop boundary — the
+ * type only exists on the original File, and reading can throw before any
+ * ProcessedFile exists. Call synchronously in the drop handler: a DataTransfer
+ * detaches after the event turn.
  */
 export function getFileTypes(files: FileList | null | undefined): string[] {
   if (!files?.length) return [];

package/packages/drop-core/readFiles.ts

@@ -53,15 +53,11 @@ async function readDirEntry(entry: any): Promise<ProcessedFile[]> {
 }
 
 /**
- * Read a DataTransfer from a drop event into ProcessedFiles.
- *
- * NOTE: `webkitGetAsEntry()` must be called synchronously inside the drop
- * handler — the DataTransfer is detached once the event turn ends. The
- * component captures entries first (see `readDroppedEntries`) then calls the
- * async readers, so this function is safe to `await`.
+ * Read a drop's DataTransfer into ProcessedFiles. `webkitGetAsEntry()` runs
+ * synchronously before the first await — the DataTransfer detaches once the
+ * event turn ends.
  */
 export async function readDataTransfer(dt: DataTransfer): Promise<ProcessedFile[]> {
-  // single zip?
   const first = dt.files?.[0];
   if (dt.files.length === 1 && first && isZipName(first.name)) {
     return readZip(first);
@@ -164,11 +160,8 @@ export function hasMultipleHtmlFilesWithoutIndex(files: ProcessedFile[]): boolea
 }
 
 /**
- * When the set has no index.html but exactly one HTML file (a lone page
- * alongside its assets, or a single dropped file), rename that file to
- * index.html — keeping its directory — so it is served at the site root
- * instead of 404ing. Content and sha are untouched. Any other set (already has
- * an index, multiple HTML files, or no HTML) is returned unchanged.
+ * A lone non-index HTML page is renamed to index.html (same directory,
+ * content/sha untouched) so it serves instead of 404ing. Other sets unchanged.
  */
 export function renameSingleNonIndexHtmlToIndex(files: ProcessedFile[]): ProcessedFile[] {
   const name = getSingleNonIndexHtmlFileName(files);

package/packages/drop-core/types.ts

@@ -11,10 +11,8 @@ export interface ProcessedFile {
 export type Digest = Record<string, string>; // { "/index.html": "<sha1>" }
 
 /**
- * Response body of `POST /api/v1/drop`. Not a canonical Deploy resource —
- * it's a mixed shape carrying both the anonymous site and the initial deploy
- * so the client has everything it needs to upload, poll, and hand off to the
- * user in one round trip.
+ * Response of `POST /api/v1/drop` — a mixed site+deploy shape, everything the
+ * client needs to upload, poll, and hand off in one round trip.
  */
 export interface DropResponse {
   /** site id (UUID) — surfaced to callers so they can build claim links */