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

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

@@ -71,6 +71,48 @@ describe('deployFiles', () => {
     expect(phases[1]).toEqual({ phase: 'uploading', uploaded: 0, total: 1 });
   });
 
+  it('retries a transient upload failure and succeeds', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      if (++attempts === 1) throw Object.assign(new Error('upload failed: 502'), { status: 502 });
+    });
+    await deployFiles(client, files, { retryDelays: [0, 0] });
+    expect(attempts).toBe(2);
+  });
+
+  it('gives up once the retry curve is exhausted', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      attempts++;
+      throw Object.assign(new Error('upload failed: 503'), { status: 503 });
+    });
+    await expect(deployFiles(client, files, { retryDelays: [0, 0] })).rejects.toThrow('503');
+    expect(attempts).toBe(3); // initial try + one per delay
+  });
+
+  it('never retries a 400/422 — the request itself is wrong', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      attempts++;
+      throw Object.assign(new Error('upload failed: 422'), { status: 422 });
+    });
+    await expect(deployFiles(client, files, { retryDelays: [0, 0] })).rejects.toThrow('422');
+    expect(attempts).toBe(1);
+  });
+
+  it('retries statusless network failures too', async () => {
+    const { client } = stubDropClient(['aaa']);
+    let attempts = 0;
+    (client.uploadFile as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      if (++attempts === 1) throw new TypeError('fetch failed');
+    });
+    await deployFiles(client, files, { retryDelays: [0] });
+    expect(attempts).toBe(2);
+  });
+
   it('throws on an empty file set before any network call', async () => {
     const { client } = stubDropClient([]);
     await expect(deployFiles(client, [])).rejects.toThrow('No files to deploy');

package/packages/drop-core/deploy.ts

@@ -1,3 +1,4 @@
+import { MAX_CONCURRENT_UPLOADS, UPLOAD_RETRY_DELAYS_MS } from './constants';
 import { getDigest } from './digest';
 import type { BuildClient, BuildResponse, BuildSite } from './buildClient';
 import type { DropClient } from './client';
@@ -5,7 +6,29 @@ import type { InferredBuildSettings } from './detectBuild';
 import type { DeployProgress, DeployResult, ProcessedFile } from './types';
 import { zipFiles, type ZipResult } from './zip';
 
-const MAX_CONCURRENT_UPLOADS = 5;
+/** Responses that mean the request itself is wrong — retrying can only repeat the answer. */
+const NON_RETRIABLE_STATUSES = new Set([400, 422]);
+
+/** Retries transient failures (5xx/429/network) — one flaky PUT shouldn't kill the deploy. */
+async function uploadWithRetry(
+  client: DropClient,
+  deployId: string,
+  file: ProcessedFile,
+  token: string,
+  retryDelays: readonly number[]
+): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await client.uploadFile(deployId, file.path, file.content, token);
+      return;
+    } catch (err) {
+      const status = (err as { status?: number }).status;
+      if (status !== undefined && NON_RETRIABLE_STATUSES.has(status)) throw err;
+      if (attempt >= retryDelays.length) throw err;
+      await new Promise(r => setTimeout(r, retryDelays[attempt]));
+    }
+  }
+}
 
 async function uploadRequired(
   client: DropClient,
@@ -13,6 +36,7 @@ async function uploadRequired(
   files: ProcessedFile[],
   required: Set<string>,
   token: string,
+  retryDelays: readonly number[],
   onUploaded?: (uploaded: number) => void
 ) {
   const queue = files.filter(f => required.has(f.sha));
@@ -21,7 +45,7 @@ async function uploadRequired(
   const worker = async () => {
     while (cursor < queue.length) {
       const f = queue[cursor++];
-      await client.uploadFile(deployId, f.path, f.content, token);
+      await uploadWithRetry(client, deployId, f, token, retryDelays);
       onUploaded?.(++done);
     }
   };
@@ -30,6 +54,8 @@ async function uploadRequired(
 
 export interface DeployOptions {
   onProgress?: (e: DeployProgress) => void;
+  /** Waits between retries of a failed file upload. Override for tests or a different curve. */
+  retryDelays?: readonly number[];
 }
 
 export async function deployFiles(
@@ -38,7 +64,7 @@ export async function deployFiles(
   opts: DeployOptions = {}
 ): Promise<DeployResult> {
   if (!files.length) throw new Error('No files to deploy');
-  const { onProgress } = opts;
+  const { onProgress, retryDelays = UPLOAD_RETRY_DELAYS_MS } = opts;
 
   onProgress?.({ phase: 'creating' });
   const token = await client.getToken();
@@ -48,8 +74,14 @@ export async function deployFiles(
   onProgress?.({ phase: 'uploading', uploaded: 0, total });
   // File PUTs and readiness polling both key off `deploy_id` (BSON), NOT
   // `deploy.id` (the site UUID) — see the note in client.waitUntilReady.
-  await uploadRequired(client, deploy.deploy_id, files, new Set(deploy.required), token, uploaded =>
-    onProgress?.({ phase: 'uploading', uploaded, total })
+  await uploadRequired(
+    client,
+    deploy.deploy_id,
+    files,
+    new Set(deploy.required),
+    token,
+    retryDelays,
+    uploaded => onProgress?.({ phase: 'uploading', uploaded, total })
   );
 
   onProgress?.({ phase: 'processing' });
@@ -60,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;
@@ -72,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,
@@ -102,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

@@ -4,12 +4,39 @@ import {
   BuildCreateError,
   BuildFailedError,
   BuildTimeoutError,
+  DeployFailedError,
+  DeployTimeoutError,
   humanizeDropError,
+  isNotAuthenticatedError,
   NotAuthenticatedError,
   SiteCreateError,
   UnsupportedDropError,
 } from './errors';
 
+describe('error codes', () => {
+  it('pins each class to its copy-proof code brand', () => {
+    expect(new UnsupportedDropError().code).toBe('unsupported-drop');
+    expect(new NotAuthenticatedError().code).toBe('not-authenticated');
+    expect(new SiteCreateError().code).toBe('site-create-failed');
+    expect(new BuildCreateError().code).toBe('build-create-failed');
+    expect(new BuildFailedError().code).toBe('build-failed');
+    expect(new BuildTimeoutError().code).toBe('build-timeout');
+    expect(new DeployFailedError().code).toBe('deploy-failed');
+    expect(new DeployTimeoutError().code).toBe('deploy-timeout');
+  });
+
+  it('recognizes a foreign-copy NotAuthenticatedError by its code', () => {
+    // Raw-TS and dist entrypoints can each load their own class copy;
+    // instanceof fails across copies, the code brand does not.
+    const foreignCopy = Object.assign(new Error('not authenticated'), {
+      code: 'not-authenticated',
+    });
+    expect(isNotAuthenticatedError(foreignCopy)).toBe(true);
+    expect(isNotAuthenticatedError(new Error('nope'))).toBe(false);
+    expect(isNotAuthenticatedError('not-authenticated')).toBe(false);
+  });
+});
+
 describe('humanizeDropError', () => {
   it('maps each typed error to its user-facing copy', () => {
     expect(humanizeDropError(new UnsupportedDropError())).toBe(
@@ -44,9 +71,13 @@ describe('humanizeDropError', () => {
     expect(humanizeDropError(new BuildCreateError(413))).toContain('too large');
   });
 
-  it('maps the shared deploy-timeout message', () => {
-    expect(humanizeDropError(new Error('Deploy did not become ready in time'))).toContain(
-      'taking longer than expected'
+  it('maps the deploy timeout and failure classes', () => {
+    expect(humanizeDropError(new DeployTimeoutError())).toContain('taking longer than expected');
+    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.'
     );
   });
 

package/packages/drop-core/errors.ts

@@ -1,11 +1,10 @@
 /**
- * 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';
+
   constructor() {
     super('unsupported single file');
     this.name = 'UnsupportedDropError';
@@ -13,22 +12,30 @@ 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';
+
   constructor(message = 'not authenticated') {
     super(message);
     this.name = 'NotAuthenticatedError';
   }
 }
 
+/**
+ * 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;
+  return err instanceof Error && (err as { code?: string }).code === 'not-authenticated';
+}
+
 /** `POST …/sites` failed, so there is nothing to build into. Carries the HTTP status. */
 export class SiteCreateError extends Error {
+  readonly code = 'site-create-failed';
   status?: number;
 
   constructor(status?: number) {
@@ -43,6 +50,7 @@ export class SiteCreateError extends Error {
  * started. Distinct from `BuildFailedError`, which is a build that ran and broke.
  */
 export class BuildCreateError extends Error {
+  readonly code = 'build-create-failed';
   status?: number;
 
   constructor(status?: number) {
@@ -52,13 +60,10 @@ 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';
+
   constructor(public reason?: string) {
     super(reason ? `build failed: ${reason}` : 'build failed');
     this.name = 'BuildFailedError';
@@ -67,12 +72,34 @@ export class BuildFailedError extends Error {
 
 /** The build hadn't settled before the poller gave up. The build itself may still finish. */
 export class BuildTimeoutError extends Error {
+  readonly code = 'build-timeout';
+
   constructor() {
     super('Build did not finish in time');
     this.name = 'BuildTimeoutError';
   }
 }
 
+/** 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';
+
+  constructor(public reason?: string) {
+    super(reason ? `deploy failed: ${reason}` : 'deploy failed');
+    this.name = 'DeployFailedError';
+  }
+}
+
+/** The deploy hadn't gone ready before the poller gave up. It may still finish. */
+export class DeployTimeoutError extends Error {
+  readonly code = 'deploy-timeout';
+
+  constructor() {
+    super('Deploy did not become ready in time');
+    this.name = 'DeployTimeoutError';
+  }
+}
+
 /**
  * Turn a raw deploy failure into copy a non-technical user can act on.
  * The original message is still tracked via analytics — this is only for display.
@@ -80,31 +107,40 @@ export class BuildTimeoutError extends Error {
 export function humanizeDropError(err: unknown): string {
   if (!(err instanceof Error)) return 'Something went wrong. Please try again.';
 
-  if (err instanceof UnsupportedDropError) {
+  // Match on the `code` brand rather than instanceof: raw-TS and dist copies
+  // of these classes can coexist (see isNotAuthenticatedError).
+  const code = (err as { code?: string }).code;
+
+  if (code === 'unsupported-drop') {
     return 'To deploy, drop a folder or a .zip file — or a single HTML page.';
   }
 
-  if (err instanceof NotAuthenticatedError) {
+  if (code === 'not-authenticated') {
     return 'Please log in to Netlify to deploy this project, then try again.';
   }
 
-  if (err instanceof SiteCreateError) {
+  if (code === 'site-create-failed') {
     return "We couldn't create a project for this build. Please try again.";
   }
 
-  // The build's own error message is the only actionable part of a build
-  // failure, so pass it straight through instead of a generic apology.
-  if (err instanceof BuildFailedError) {
-    return err.reason
-      ? `Your build failed: ${err.reason}`
+  // The failure's own error message is the only actionable part, so pass it
+  // straight through instead of a generic apology.
+  if (code === 'build-failed') {
+    const reason = (err as BuildFailedError).reason;
+    return reason
+      ? `Your build failed: ${reason}`
       : 'Your build failed. Check your build settings and try again.';
   }
+  if (code === 'deploy-failed') {
+    const reason = (err as DeployFailedError).reason;
+    return reason ? `Your deploy failed: ${reason}` : 'Your deploy failed. Please try again.';
+  }
 
-  if (err instanceof BuildTimeoutError) {
+  if (code === 'build-timeout') {
     return 'Your build is taking longer than expected. It may still finish — check your Netlify dashboard.';
   }
 
-  if (err.message === 'Deploy did not become ready in time') {
+  if (code === 'deploy-timeout') {
     return 'Your site is taking longer than expected to go live. Please try again in a moment.';
   }
   // fetch() rejects with a TypeError when the network is unreachable (offline, DNS, CORS, etc).

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

@@ -1,14 +1,44 @@
+/**
+ * The public surface of drop-core — nothing is public unless named here.
+ * `export *` is reserved for the three modules that are contracts in their
+ * entirety: types, errors, and the analytics event map.
+ */
+
 export * from './types';
-export * from './digest';
-export * from './readFiles';
-export * from './fileTypes';
-export * from './detectBuild';
-export * from './client';
-export * from './authedApi';
-export * from './authedDropClient';
-export * from './buildClient';
-export * from './zip';
-export * from './buildStash';
-export * from './deploy';
 export * from './errors';
 export * from './analytics';
+
+// Reading a drop into deployable files
+export {
+  getSingleNonIndexHtmlFileName,
+  hasMultipleHtmlFilesWithoutIndex,
+  readDataTransfer,
+  readFileList,
+  renameSingleNonIndexHtmlToIndex,
+} from './readFiles';
+export { getFileTypes } from './fileTypes';
+
+// Build detection and archive synthesis
+export { detectBuild, inferBuildSettings } from './detectBuild';
+export type { BuildDetection, BuildReason, InferredBuildSettings } from './detectBuild';
+export { zipFiles } from './zip';
+export type { ZipOptions, ZipResult } from './zip';
+
+// Deploy clients — anonymous (claim flow) and authenticated (into the account)
+export { AnonymousDropClient } from './client';
+export type { DropClient } from './client';
+export { AuthenticatedDropClient } from './authedDropClient';
+export type { AuthenticatedDropClientConfig } from './authedDropClient';
+export { AuthenticatedBuildClient } from './buildClient';
+export type { AuthenticatedBuildClientConfig, BuildClient, BuildResponse } from './buildClient';
+
+// Deploy orchestration
+export { deployBuild, deployFiles, deployZippedBuild } from './deploy';
+export type { BuildDeployOptions, BuildDeployResult, DeployOptions } from './deploy';
+
+// Carrying a build drop across the signup round-trip
+export { clearDropStash, hasDropStashMarker, loadDropStash, saveDropStash } from './buildStash';
+export type { DropBuildStash } from './buildStash';
+
+// Documented defaults consumers may want to reference
+export { DEFAULT_API_BASE, DEFAULT_PROXY_BASE, UPLOAD_RETRY_DELAYS_MS } from './constants';

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

@@ -81,7 +81,6 @@ describe('readFileList', () => {
     const files = await readFileList(
       asFileList([new File([bytes.buffer.slice(0) as ArrayBuffer], 'my-site.zip')])
     );
-    // Junk gone, common "my-site/" root stripped.
     expect(files.map(f => f.path).sort()).toEqual(['/css/site.css', '/index.html']);
   });
 });

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);