@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/client/hooks/chat/composer/file-drop.ts

@@ -0,0 +1,226 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * OS file drag-and-drop for the chat composer.
+ *
+ * Three browser rules shape this module:
+ *
+ * 1. A `drop` is only delivered when the preceding `dragover` was cancelled, so
+ *    the handlers belong on the whole composer card — a drop aimed at the
+ *    textarea bubbles up to it, and cancelling there also suppresses the
+ *    browser's own "insert the dropped file's path as text" default.
+ * 2. A dropped DIRECTORY is not a readable File: `dataTransfer.files` carries a
+ *    size-0 stub for it. Only `DataTransferItem.webkitGetAsEntry()` reveals it
+ *    as a directory, so those are walked recursively and attached file by file.
+ * 3. A file dropped anywhere the app does not cancel lands in the tab as
+ *    `file://` navigation, which throws Kabmo away. The guard below is
+ *    window-wide for exactly that reason; it only ever cancels file drags, so
+ *    text and URL drops keep their native behaviour.
+ *
+ * What counts as a file drag is decided in `drop-payload.ts`, because hosts
+ * disagree: a download dragged out of a web page offers no File at all, only a
+ * URL, and those references are handed back to the caller to resolve.
+ *
+ * The drag data store is cleared the moment the drop handler returns, so every
+ * store-bound read (`getAsFile`, `webkitGetAsEntry`, `getData`) happens
+ * synchronously; the entries and Files they return stay valid while the walk
+ * awaits.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import type { TargetedDragEvent } from 'preact';
+import { collectDroppedFileUris, hasDraggedFiles } from '@/client/hooks/chat/composer/drop-payload';
+import { primeFileReads, primedPrefix } from '@/client/hooks/chat/composer/file-reads';
+import type { PrimedReads } from '@/client/hooks/chat/composer/file-reads';
+import {
+  expandDroppedFiles,
+  readDroppedEntries,
+  MAX_DROP_DEPTH,
+  MAX_DROPPED_FILES,
+} from '@/client/hooks/chat/composer/drop-entries';
+import type { DroppedEntries } from '@/client/hooks/chat/composer/drop-entries';
+
+/** Reason shown when a drop yielded more than the composer can take. */
+export const DROP_LIMIT_NOTICE =
+  `Some files were skipped — a drop is limited to ${MAX_DROPPED_FILES} files and ${MAX_DROP_DEPTH} folder levels deep.`;
+
+export interface UseFileDropOptions {
+  /**
+   * Called once per drop with every file it resolved to (directories expanded),
+   * plus any file REFERENCES the host offered instead of bytes (a download
+   * dragged out of a web page) for the caller to resolve server-side.
+   */
+  onFiles: (files: File[], incomplete: boolean, references: string[], primed: PrimedReads) => void;
+  /** While true a drop is cancelled but not attached — the composer is closed. */
+  disabled?: boolean;
+}
+
+/** Drag handlers to spread onto the drop target. */
+export interface FileDropProps {
+  onDragEnter: (e: TargetedDragEvent<HTMLElement>) => void;
+  onDragOver: (e: TargetedDragEvent<HTMLElement>) => void;
+  onDragLeave: (e: TargetedDragEvent<HTMLElement>) => void;
+  onDrop: (e: TargetedDragEvent<HTMLElement>) => void;
+}
+
+export interface UseFileDropResult {
+  /** True while a file drag hovers the bound element (drives the overlay). */
+  isDragging: boolean;
+  dropProps: FileDropProps;
+}
+
+export function useFileDrop({ onFiles, disabled = false }: UseFileDropOptions): UseFileDropResult {
+  const [isDragging, setIsDragging] = useState(false);
+  // dragenter/dragleave fire for every nested child the pointer crosses, so a
+  // boolean flag drops to false the instant the cursor moves from the card onto
+  // the textarea. Counting them keeps the overlay steady.
+  const depthRef = useRef(0);
+  // Latest callback and flag behind refs, so the handlers stay referentially
+  // stable and the window guard sees the current `disabled`.
+  const onFilesRef = useRef(onFiles);
+  onFilesRef.current = onFiles;
+  const disabledRef = useRef(disabled);
+  disabledRef.current = disabled;
+
+  const reset = useCallback(() => {
+    depthRef.current = 0;
+    setIsDragging(false);
+  }, []);
+
+  // A drag can end without reaching this element again — released over the
+  // page, cancelled with Escape, or its source node unmounted mid-drag. The
+  // composer's own handlers have already run by the time these fire, so this
+  // only clears state the drop handler did not.
+  useEffect(() => {
+    window.addEventListener('dragend', reset);
+    window.addEventListener('drop', reset);
+    return () => {
+      window.removeEventListener('dragend', reset);
+      window.removeEventListener('drop', reset);
+    };
+  }, [reset]);
+
+  // Files dropped anywhere else would navigate the tab to `file://` and discard
+  // Kabmo, so the default is cancelled app-wide. This runs after the
+  // composer's own drop handler (the event bubbles up to window), by which point
+  // that handler has already read the data store it needed.
+  useEffect(() => {
+    const guard = (e: DragEvent) => {
+      if (hasDraggedFiles(e.dataTransfer)) e.preventDefault();
+    };
+    window.addEventListener('dragover', guard);
+    window.addEventListener('drop', guard);
+    return () => {
+      window.removeEventListener('dragover', guard);
+      window.removeEventListener('drop', guard);
+    };
+  }, []);
+
+  const onDragEnter = useCallback((e: TargetedDragEvent<HTMLElement>) => {
+    if (!hasDraggedFiles(e.dataTransfer)) return;
+    e.preventDefault();
+    if (disabledRef.current) return;
+    depthRef.current += 1;
+    setIsDragging(true);
+  }, []);
+
+  const onDragOver = useCallback((e: TargetedDragEvent<HTMLElement>) => {
+    if (!hasDraggedFiles(e.dataTransfer)) return;
+    // Required: without it the browser refuses the drop and navigates to the
+    // file instead of handing it to the app.
+    e.preventDefault();
+    if (!e.dataTransfer) return;
+    // `none` is the only cursor that tells the truth about a closed composer.
+    e.dataTransfer.dropEffect = disabledRef.current ? 'none' : 'copy';
+  }, []);
+
+  // Not gated on the payload: `dataTransfer.types` can already be empty on
+  // dragleave. The counter is the gate — a text drag never raised it.
+  const onDragLeave = useCallback(() => {
+    if (depthRef.current === 0) return;
+    depthRef.current -= 1;
+    if (depthRef.current === 0) setIsDragging(false);
+  }, []);
+
+  const onDrop = useCallback((e: TargetedDragEvent<HTMLElement>) => {
+    const dt = e.dataTransfer;
+    // Read the payload in ONE pass before anything else touches it:
+    // `getAsFile()` and `webkitGetAsEntry()` are not pure accessors on a
+    // file-manager drag, and each call can consume state the other needs.
+    const entries: DroppedEntries = dt ? readDroppedEntries(dt) : { files: [], directories: [], fallbacks: new Map() };
+    const references = dt ? collectDroppedFileUris(dt) : [];
+
+    if (!dt || !hasDraggedFiles(dt)) return;
+    e.preventDefault();
+    reset();
+    if (disabledRef.current) return;
+
+    // START THE READS NOW, in the drop handler's own tick. A dropped File's
+    // read permission is released when this handler returns, and a read started
+    // afterwards fails permanently — the chip rendered with the right name and
+    // size while its contents never arrived, on every retry. `FileReader` takes
+    // the permission at call time, so starting here is what makes the bytes
+    // reachable; the pipeline only awaits these later.
+    const primed = primeFileReads(entries.files, entries.fallbacks);
+
+    if (entries.files.length === 0 && entries.directories.length === 0) {
+      // No File at all: the host named the file without handing it over, and the
+      // reference resolver is the only route left to its contents.
+      if (references.length > 0) onFilesRef.current([], false, references, primed);
+      return;
+    }
+
+    void expandDroppedFiles(entries).then(async ({ files: resolved, incomplete }) => {
+      const carries = resolved.length > 0 ? await carriesBytes(resolved, primed) : false;
+      // A File that carries bytes is attached directly. Deciding from metadata
+      // instead — "size 0 and no type, so it must be a path stub" — misread a
+      // real file whose size the browser had not filled in, and sent it to the
+      // reference resolver, which only reads inside the allow-list. The file
+      // was then refused with no way for the user to tell why. Bytes settle it.
+      if (resolved.length > 0 && carries) {
+        onFilesRef.current(resolved, incomplete, [], primed);
+        return;
+      }
+      if (references.length > 0) {
+        onFilesRef.current([], incomplete, references, primed);
+        return;
+      }
+      // Files that declare no bytes are attached as-is; the attachment hook
+      // reports the ones that never produced content.
+      if (resolved.length > 0) onFilesRef.current(resolved, incomplete, [], primed);
+    });
+  }, [reset]);
+
+  return { isDragging, dropProps: { onDragEnter, onDragOver, onDragLeave, onDrop } };
+}
+
+/**
+ * Whether any dropped file actually holds bytes.
+ *
+ * A promised file (another app's drag) reports `size: 0` until its contents
+ * land, so the check reads rather than trusting the declared size. One readable
+ * file is enough: the batch is attached as a unit, and a member that stays
+ * empty is reported by the attachment hook rather than by re-routing the whole
+ * drop.
+ */
+export async function carriesBytes(files: File[], primed?: PrimedReads): Promise<boolean> {
+  const sample = files.slice(0, 4);
+  const results = await Promise.all(sample.map(async (file) => {
+    if (file.size > 0) return true;
+    // A stub declaring no size is settled by its bytes — read from the primed
+    // prefix where the drop provided one, because a `slice()` started after the
+    // drop window closes is not authorized to read a dropped file at all.
+    const bytes = await primedPrefix(file, primed);
+    if (bytes !== undefined) return bytes.byteLength > 0;
+    try {
+      const raw = await file.slice(0, 1).arrayBuffer();
+      return raw.byteLength > 0;
+    } catch {
+      return false;
+    }
+  }));
+  return results.some(Boolean);
+}

package/src/client/hooks/chat/composer/file-reads.test.ts

@@ -0,0 +1,211 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The priming contract, which is a TIMING contract.
+ *
+ * A dropped `File` may only be read from a read begun while the drop handler is
+ * still running; a read started afterwards fails with `NotReadableError` and
+ * keeps failing. These tests pin the two halves of that: `primeFileReads`
+ * issues its read synchronously, and the read pipeline consumes the primed
+ * result instead of starting a second, unauthorized one.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { primeFileReads, readFileTextWithRetry } from '@/client/hooks/chat/composer/file-reads';
+
+/** A `FileReader` that answers from a lookup, counting the reads it was asked for. */
+function installFakeReader(
+  contents: Map<string, string>,
+  options: { failDataUrl?: boolean; unreadable?: Set<File> } = {},
+) {
+  const calls: string[] = [];
+  /** A file the browser refuses to read, whatever its metadata says. */
+  const dead = (file: File) => options.unreadable?.has(file) ?? false;
+  class FakeReader {
+    result: string | ArrayBuffer | null = null;
+    error: { name: string; message: string } | null = null;
+    onload: (() => void) | null = null;
+    onerror: (() => void) | null = null;
+    onabort: (() => void) | null = null;
+
+    readAsArrayBuffer() {
+      calls.push('arrayBuffer');
+      queueMicrotask(() => {
+        if (options.failDataUrl) {
+          this.error = { name: 'NotReadableError', message: 'unreadable' };
+          this.onerror?.();
+          return;
+        }
+        this.result = new Uint8Array([1, 2, 3]).buffer;
+        this.onload?.();
+      });
+    }
+
+    readAsDataURL(file: File) {
+      calls.push(`dataURL:${file.name}`);
+      const body = dead(file) ? undefined : contents.get(file.name);
+      queueMicrotask(() => {
+        if (options.failDataUrl || body === undefined) {
+          this.error = {
+            name: 'NotReadableError',
+            message: 'permission problems that have occurred after a reference to a file was acquired',
+          };
+          this.onerror?.();
+          return;
+        }
+        // `data:<mime>;base64,<payload>` — the real reader's shape.
+        const base64 = btoa(String.fromCharCode(...new TextEncoder().encode(body)));
+        this.result = `data:text/plain;base64,${base64}`;
+        this.onload?.();
+      });
+    }
+
+    readAsText(file: File) {
+      calls.push(`text:${file.name}`);
+      const body = dead(file) ? undefined : contents.get(file.name);
+      queueMicrotask(() => {
+        if (body === undefined) {
+          this.error = { name: 'NotReadableError', message: 'unreadable' };
+          this.onerror?.();
+          return;
+        }
+        this.result = body;
+        this.onload?.();
+      });
+    }
+  }
+  (globalThis as unknown as { FileReader: unknown }).FileReader = FakeReader;
+  return calls;
+}
+
+const originalFileReader = (globalThis as unknown as { FileReader: unknown }).FileReader;
+
+afterEach(() => {
+  (globalThis as unknown as { FileReader: unknown }).FileReader = originalFileReader;
+});
+
+describe('primeFileReads', () => {
+  test('starts the read synchronously, in the caller\'s own tick', () => {
+    const calls = installFakeReader(new Map([['a.md', 'body']]));
+    const file = new File(['body'], 'a.md', { type: 'text/markdown' });
+
+    primeFileReads([file]);
+
+    // The point of the module: the calls are already made when this returns. A
+    // read deferred to a microtask would be outside the drop handler's tick and
+    // therefore unauthorized.
+    expect(calls.filter((c) => c.startsWith('dataURL:'))).toEqual(['dataURL:a.md']);
+    expect(calls.filter((c) => c === 'arrayBuffer').length).toBe(1);
+  });
+
+  test('reads each file once however many batches carry it', () => {
+    const calls = installFakeReader(new Map([['a.md', 'body']]));
+    const file = new File(['body'], 'a.md', { type: 'text/markdown' });
+
+    primeFileReads([file, file]);
+
+    expect(calls.filter((c) => c.startsWith('dataURL:'))).toEqual(['dataURL:a.md']);
+  });
+
+  test('stays inside the attach cap, so an oversized drop is not read whole', () => {
+    const calls = installFakeReader(new Map());
+    const files = Array.from({ length: 80 }, (_, i) => new File(['x'], `f${i}.txt`));
+
+    primeFileReads(files);
+
+    expect(calls.filter((c) => c.startsWith('dataURL:')).length).toBeLessThanOrEqual(50);
+  });
+});
+
+describe('a drop that exposes one file as two objects', () => {
+  // A drop can hand over the same file twice — once in `files`, once in the item
+  // list — and only one of the two objects actually reads. Which one is not
+  // knowable up front: the same drop read fine in a browser tab and failed in an
+  // installed app window, with the unreadable object still reporting the right
+  // name and size. So the read path tries the counterpart instead of trusting
+  // the choice.
+  test('falls back to the counterpart object when the primary will not read', async () => {
+    const primary = new File(['x'.repeat(40)], 'notes.md', { type: 'text/markdown' });
+    const counterpart = new File(['rescued body'], 'notes.md', { type: 'text/markdown' });
+    // The primary refuses to read while declaring bytes; the counterpart reads.
+    const calls = installFakeReader(
+      new Map([['notes.md', 'rescued body']]),
+      { unreadable: new Set([primary]) },
+    );
+    const primed = primeFileReads([primary], new Map([[primary, counterpart]]));
+
+    const content = await readFileTextWithRetry(primary, primed);
+
+    expect(content).toBe('rescued body');
+    expect(calls.filter((c) => c.startsWith('dataURL:')).length).toBe(2);
+
+    // Not vacuous: with no counterpart primed the same file stays unreadable,
+    // which is exactly the failure this pairing exists to prevent.
+    const alone = primeFileReads([primary]);
+    expect(await readFileTextWithRetry(primary, alone)).toBeNull();
+  });
+
+  test('the counterpart is primed in the same tick, not read on demand', () => {
+    const primary = new File(['x'], 'a.md', { type: 'text/markdown' });
+    const counterpart = new File(['y'], 'a.md', { type: 'text/markdown' });
+    const calls = installFakeReader(new Map());
+
+    primeFileReads([primary], new Map([[primary, counterpart]]));
+
+    // Both reads must already be in flight when the call returns: one started
+    // later would be outside the drop's permission window.
+    expect(calls.filter((c) => c.startsWith('dataURL:')).length).toBe(2);
+  });
+});
+
+describe('readFileTextWithRetry with a primed read', () => {
+  test('returns the primed body without starting another read', async () => {
+    const calls = installFakeReader(new Map([['a.md', 'primed body']]));
+    const file = new File(['primed body'], 'a.md', { type: 'text/markdown' });
+    const primed = primeFileReads([file]);
+
+    const content = await readFileTextWithRetry(file, primed);
+
+    expect(content).toBe('primed body');
+    // Exactly one read: a second would be the unauthorized one, and its failure
+    // would be indistinguishable from an unreadable file.
+    expect(calls.filter((c) => c.startsWith('dataURL:'))).toEqual(['dataURL:a.md']);
+  });
+
+  test('falls back to its own reads when the file was never primed', async () => {
+    const calls = installFakeReader(new Map([['b.md', 'late body']]));
+    const file = new File(['late body'], 'b.md', { type: 'text/markdown' });
+
+    const content = await readFileTextWithRetry(file);
+
+    expect(content).toBe('late body');
+    expect(calls.length).toBeGreaterThan(0);
+  });
+
+  test('retries a primed read that came back empty, for a promised file', async () => {
+    // The primed read lands before the bytes do; the retry loop is what covers
+    // that, so it must not be short-circuited by the primed attempt.
+    const calls = installFakeReader(new Map());
+    const file = new File(['x'.repeat(100)], 'promised.md', { type: 'text/markdown' });
+    const primed = primeFileReads([file]);
+
+    const content = await readFileTextWithRetry(file, primed);
+
+    // Null, not '': the file DECLARES bytes, so an empty body is a failure the
+    // caller reports rather than a genuinely empty file it accepts.
+    expect(content).toBeNull();
+    expect(calls.filter((c) => c === 'text:promised.md').length).toBeGreaterThan(1);
+  });
+
+  test('accepts an empty body for a file that declares no bytes', async () => {
+    // A genuinely empty file is empty forever; retrying it cannot change that,
+    // so it settles as empty rather than as a failure.
+    installFakeReader(new Map());
+    const file = new File([], 'empty.md', { type: 'text/markdown' });
+
+    expect(await readFileTextWithRetry(file, primeFileReads([file]))).toBe('');
+  });
+});

package/src/client/hooks/chat/composer/file-reads.ts

@@ -0,0 +1,238 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reading a dropped `File`'s bytes — and the one browser rule that makes the
+ * TIMING of that read part of the contract.
+ *
+ * A file that arrives through a drop is not an ordinary `Blob`. The browser
+ * holds a permission reference to the real file, and that reference is released
+ * when the `drop` event's handler returns. A read started after that point
+ * fails with `NotReadableError: ... permission problems that have occurred
+ * after a reference to a file was acquired`, and it fails PERMANENTLY — every
+ * retry after it fails the same way, because the reference is gone rather than
+ * busy. This is why a dropped file showed a chip with a correct name and size
+ * while its contents never arrived, and why three retries did not help.
+ *
+ * `FileReader.readAs*` checks the permission when it is CALLED, not when it
+ * completes. So the read must be STARTED synchronously inside the drop handler;
+ * awaiting its result later is fine. `primeFileReads` is that start, and every
+ * later consumer takes the already-running read rather than beginning its own.
+ */
+
+
+/** How many times a read that came back empty is retried before giving up. */
+export const READ_ATTEMPTS = 3;
+
+/** Base delay between read attempts; a promised file needs a beat to land. */
+export const READ_RETRY_MS = 60;
+
+/**
+ * How many files a single drop primes up front. Matches `MAX_DROPPED_FILES`:
+ * priming beyond what can be attached would hold bytes the budget will reject.
+ */
+const MAX_PRIMED_FILES = 50;
+
+export function delay(ms: number): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, ms);
+  return promise;
+}
+
+/**
+ * Start a data-URL read and return the still-running promise.
+ *
+ * MUST be called synchronously from the drop handler — see the module note. The
+ * result is the whole `data:<mime>;base64,<payload>` string, because the two
+ * consumers want different halves of it: an image takes the payload, a text file
+ * decodes it back to text.
+ */
+function startDataUrlRead(file: File): Promise<string | null> {
+  const { promise, resolve } = Promise.withResolvers<string | null>();
+  const reader = new FileReader();
+  reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : null);
+  reader.onerror = () => {
+    resolve(null);
+  };
+  reader.onabort = () => resolve(null);
+  reader.readAsDataURL(file);
+  return promise;
+}
+
+/**
+ * A read already in flight, started while the drop's permission was live.
+ *
+ * `dataUrl` and `prefix` are the PRIMARY file's reads. `spare` holds the reads
+ * of the same drop's other `File` object, tried when the primary yields nothing:
+ * a drop can expose one file twice and only one of the two objects reads, with
+ * neither the metadata nor the context saying which. See `drop-entries.ts`.
+ */
+export interface PrimedRead {
+  /** The whole file as a data URL — the authorized read of a dropped file. */
+  dataUrl: Promise<string | null>;
+  /**
+   * The leading bytes, for the text sniff and the empty-stub check.
+   *
+   * Those two ask a `File` for bytes through `slice().arrayBuffer()`, which is
+   * subject to the same permission as `FileReader` — so they have to be served
+   * from a read started in the drop's tick as well, not started on demand.
+   */
+  prefix: Promise<Uint8Array | null>;
+  /** The counterpart object's reads, when the payload exposed the file twice. */
+  spare?: PrimedRead;
+}
+
+export type PrimedReads = Map<File, PrimedRead>;
+
+/** Bytes sampled to decide whether an unclassified file is text. */
+const PREFIX_BYTES = 4096;
+
+function startPrefixRead(file: File): Promise<Uint8Array | null> {
+  const { promise, resolve } = Promise.withResolvers<Uint8Array | null>();
+  const reader = new FileReader();
+  reader.onload = () => resolve(reader.result instanceof ArrayBuffer ? new Uint8Array(reader.result) : null);
+  reader.onerror = () => resolve(null);
+  reader.onabort = () => resolve(null);
+  reader.readAsArrayBuffer(file.slice(0, PREFIX_BYTES));
+  return promise;
+}
+
+/**
+ * Begin reading every file NOW, in the drop handler's own tick.
+ *
+ * Returns a lookup the later async pipeline consults instead of reading the
+ * `File` itself. Files that were not primed (a directory walk discovers its
+ * children after the tick) simply have no entry and fall back to a fresh read.
+ */
+export function primeFileReads(files: readonly File[], fallbacks?: Map<File, File>): PrimedReads {
+  const primed: PrimedReads = new Map();
+  // Bounded by the same cap the attach path applies: a read is buffered as a
+  // data URL, so priming a thousand-file drop would hold every byte twice
+  // before the budget had a chance to reject any of them.
+  for (const file of files.slice(0, MAX_PRIMED_FILES)) {
+    if (primed.has(file)) continue;
+    const counterpart = fallbacks?.get(file);
+    primed.set(file, {
+      dataUrl: startDataUrlRead(file),
+      prefix: startPrefixRead(file),
+      // Primed in the same tick for the same reason: a fallback whose own read
+      // starts after the drop window closes is not authorized either.
+      ...(counterpart
+        ? { spare: { dataUrl: startDataUrlRead(counterpart), prefix: startPrefixRead(counterpart) } }
+        : {}),
+    });
+  }
+  return primed;
+}
+
+/**
+ * The primed leading bytes, or `undefined` when the file was never primed.
+ *
+ * An empty array means the read was attempted and yielded nothing — which is
+ * also what a genuine empty file gives, and what the sniff should see.
+ */
+export async function primedPrefix(file: File, primed?: PrimedReads): Promise<Uint8Array | undefined> {
+  const started = primed?.get(file);
+  if (!started) return undefined;
+  const bytes = await started.prefix;
+  if (bytes && bytes.byteLength > 0) return bytes;
+  if (started.spare) {
+    const spare = await started.spare.prefix;
+    if (spare && spare.byteLength > 0) return spare;
+  }
+  return bytes ?? new Uint8Array(0);
+}
+
+/** The base64 payload of a data URL, or null when there is none. */
+export function base64Of(dataUrl: string | null): string | null {
+  if (dataUrl === null) return null;
+  const comma = dataUrl.indexOf(',');
+  return comma === -1 ? null : dataUrl.slice(comma + 1);
+}
+
+/**
+ * Decode a data URL's payload back to text, or null when it cannot be decoded.
+ *
+ * Null covers both "no payload" and "payload is not text": a dropped binary
+ * arrives through the same data-URL read, and its bytes are not a UTF-8 string.
+ */
+export function textOf(dataUrl: string | null): string | null {
+  const base64 = base64Of(dataUrl);
+  if (base64 === null) return null;
+  try {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder('utf-8').decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/** Read a File as base64, or null when the read fails. */
+export async function readAsDataUrl(file: File, primed?: PrimedReads): Promise<string | null> {
+  const started = primed?.get(file);
+  if (started) {
+    const payload = base64Of(await started.dataUrl);
+    if (payload !== null) return payload;
+    // The primary object did not read; the drop's other object for the same file
+    // may. One of the two is unreadable in a given context and it is not the one
+    // the metadata suggests.
+    if (started.spare) return base64Of(await started.spare.dataUrl);
+    return null;
+  }
+  return base64Of(await startDataUrlRead(file));
+}
+
+/** Read a File as text through `readAsText`, or null when the read fails. */
+function readAsTextDirect(file: File): Promise<string | null> {
+  const { promise, resolve } = Promise.withResolvers<string | null>();
+  const reader = new FileReader();
+  reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : null);
+  reader.onerror = () => {
+    resolve(null);
+  };
+  reader.onabort = () => resolve(null);
+  reader.readAsText(file);
+  return promise;
+}
+
+/**
+ * Read a File's text, preferring a read that was already started.
+ *
+ * The primed read is the one that matters: it is the only one the browser is
+ * guaranteed to authorize for a dropped file (see the module note), so it is
+ * consulted first and a non-empty body from it ends the call. The loop behind it
+ * exists for a PROMISED file — another app's drag, whose bytes land a moment
+ * after the entry exists — and for a file that was never primed at all.
+ *
+ * Returns null when no attempt produced a body for a file that declares bytes.
+ */
+export async function readFileTextWithRetry(file: File, primed?: PrimedReads): Promise<string | null> {
+  const started = primed?.get(file);
+  if (started) {
+    const content = textOf(await started.dataUrl);
+    if (content !== null && content.length > 0) return content;
+    if (started.spare) {
+      const spare = textOf(await started.spare.dataUrl);
+      if (spare !== null && spare.length > 0) return spare;
+    }
+  }
+
+  let last: string | null = null;
+  for (let attempt = 0; attempt < READ_ATTEMPTS; attempt += 1) {
+    last = await readAsTextDirect(file);
+    if (last === null || last.length === 0) {
+      const viaDataUrl = textOf(await startDataUrlRead(file));
+      if (viaDataUrl !== null && viaDataUrl.length > 0) return viaDataUrl;
+    }
+    if (last !== null && last.length > 0) return last;
+    // An empty body is the real answer once the file has had a beat to
+    // materialize AND declares no bytes of its own.
+    if (file.size === 0 && attempt > 0) return last ?? '';
+    await delay(READ_RETRY_MS);
+  }
+  return last;
+}