@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/client/hooks/chat/composer/auto-grow.test.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Composer growth: `useAutoGrow` sizes a modal composer to its content under a
+ * ceiling. Both of its rules are invisible without measuring: the box must be
+ * collapsed to `auto` BEFORE `scrollHeight` is read (with its old height in
+ * place, `scrollHeight` reports the box's own size and a deletion could never
+ * bring it back down), and the result must be clamped between the floor and
+ * the ceiling so a pasted transcript cannot push the send button off screen.
+ *
+ * Split verbatim from `pipeline.test.ts` so both files stay under the repo's
+ * 350-line ceiling; the attach-and-send pipeline keeps its own file.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { useAutoGrow } from '@/client/hooks/chat/composer/auto-grow';
+
+const DOM_GLOBALS = [
+  'window', 'document', 'navigator', 'HTMLElement', 'Element', 'Node', 'Event', 'CustomEvent',
+  'getComputedStyle', 'File', 'Blob', 'FileReader', 'URL', 'FormData',
+] as const;
+
+let container: HTMLElement;
+
+/** The runner's own globals, put back once this file's DOM work is done. */
+const native: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in native)) native[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (native[key] === undefined) delete target[key];
+    else target[key] = native[key];
+  }
+});
+
+afterEach(() => {
+  if (container) render(null, container);
+  container?.remove();
+});
+
+// ── useAutoGrow ─────────────────────────────────────────────────────────────
+
+interface Measured {
+  /** The inline height at each `scrollHeight` read, in order. */
+  heights: string[];
+  scrollHeight: number;
+}
+
+function GrowProbe({ value, min, max, measured }: {
+  value: string;
+  min: number;
+  max: number;
+  measured: Measured;
+}) {
+  const ref = useAutoGrow({ value, minHeightPx: min, maxHeightPx: max });
+  return h('textarea', {
+    ref: (el: HTMLTextAreaElement | null) => {
+      if (!el) return;
+      (ref as { current: HTMLTextAreaElement | null }).current = el;
+      if (Object.getOwnPropertyDescriptor(el, 'scrollHeight')) return;
+      Object.defineProperty(el, 'scrollHeight', {
+        configurable: true,
+        get: () => {
+          measured.heights.push(el.style.height);
+          return measured.scrollHeight;
+        },
+      });
+    },
+  });
+}
+
+function box(scrollHeight: number): Measured {
+  return { heights: [], scrollHeight };
+}
+
+async function mountGrow(measured: Measured, value: string, min: number, max: number) {
+  container = document.body.appendChild(document.createElement('div'));
+  await act(async () => { render(h(GrowProbe, { value, min, max, measured }), container); });
+  return container.querySelector('textarea') as HTMLTextAreaElement;
+}
+
+describe('useAutoGrow', () => {
+  test('content under the ceiling sets the height it needs', async () => {
+    const measured = box(200);
+    const el = await mountGrow(measured, 'two lines', 80, 480);
+    expect(el.style.height).toBe('200px');
+    expect(el.style.overflowY).toBe('hidden');
+  });
+
+  test('a paste past the ceiling stops there and scrolls', async () => {
+    const measured = box(900);
+    const el = await mountGrow(measured, 'a very long paste', 80, 480);
+    expect(el.style.height).toBe('480px');
+    expect(el.style.overflowY).toBe('auto');
+  });
+
+  test('an empty box never shrinks below its floor', async () => {
+    const measured = box(12);
+    const el = await mountGrow(measured, '', 80, 480);
+    expect(el.style.height).toBe('80px');
+    expect(el.style.overflowY).toBe('hidden');
+  });
+
+  test('the box is collapsed before each measurement, so a deletion can shrink it', async () => {
+    const measured = box(900);
+    const el = await mountGrow(measured, 'long', 80, 480);
+    // The effect reads `scrollHeight` twice: the first read is the one that
+    // decides the height and it MUST see the collapsed box, never the previous
+    // pixel height. The second is the overflow check, after the height landed.
+    expect(measured.heights).toEqual(['auto', '480px']);
+    expect(el.style.height).toBe('480px');
+
+    measured.scrollHeight = 120;
+    await act(async () => { render(h(GrowProbe, { value: 'short', min: 80, max: 480, measured }), container); });
+    expect(measured.heights).toEqual(['auto', '480px', 'auto', '120px']);
+    expect(el.style.height).toBe('120px');
+    expect(el.style.overflowY).toBe('hidden');
+  });
+
+  test('raising the floor re-measures with the new minimum', async () => {
+    const measured = box(50);
+    await mountGrow(measured, 'x', 80, 480);
+    await act(async () => { render(h(GrowProbe, { value: 'x', min: 120, max: 480, measured }), container); });
+    const el = container.querySelector('textarea') as HTMLTextAreaElement;
+    expect(el.style.height).toBe('120px');
+  });
+});

package/src/client/hooks/chat/composer/auto-grow.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Composer growth for a MODAL composer: the textarea sizes itself to its
+ * content up to a ceiling, and the enclosing card grows with it.
+ *
+ * The chat composer deliberately does NOT do this — its textarea is a fixed
+ * box that scrolls, because the timeline owns the space and a composer that
+ * grew on every paste would move the conversation under the reader's cursor.
+ * Inside a modal there is nothing to push around: the card is the only thing on
+ * screen, so growing it is free, and a multi-paragraph prompt is then visible
+ * while it is written.
+ *
+ * The ceiling is the whole point of the module: unbounded growth turns a pasted
+ * transcript into a card taller than the viewport, with the toolbar and the
+ * send button pushed off screen. `maxHeightPx` keeps the composer a composer,
+ * and the textarea scrolls past it.
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+
+export interface UseAutoGrowOptions {
+  /** Current text; a change re-measures. */
+  value: string;
+  /** Height the box is never smaller than (its `min-h-*` class, in px). */
+  minHeightPx: number;
+  /** Height the box never exceeds; content past it scrolls. */
+  maxHeightPx: number;
+}
+
+export function useAutoGrow({ value, minHeightPx, maxHeightPx }: UseAutoGrowOptions) {
+  const ref = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    // Reset first: `scrollHeight` reports the height the box would need AT its
+    // current size, so measuring without collapsing would never shrink the box
+    // back down after a deletion.
+    el.style.height = 'auto';
+    const next = Math.min(Math.max(el.scrollHeight, minHeightPx), maxHeightPx);
+    el.style.height = `${next}px`;
+    // Scroll only once the content actually exceeds the ceiling.
+    el.style.overflowY = el.scrollHeight > maxHeightPx ? 'auto' : 'hidden';
+  }, [value, minHeightPx, maxHeightPx]);
+
+  return ref;
+}

package/src/client/hooks/chat/composer/browser-context.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Sibling-panel bridge: listens for the browser panel's "include page" event
+ * and appends a structured page-context block to the chat draft. Lives beside
+ * the timeline hooks because they own the persisted draft (`chat.draft`).
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+import { BROWSER_INCLUDE_PAGE_EVENT } from '@/shared/lib/browser/page-context';
+import { readString } from '@/shared/lib/browser/util';
+import { isRecord } from '@/shared/lib/util/guards';
+
+type DraftSetter = (value: string | ((prev: string) => string)) => void;
+
+/** Append the browser page-context block to the composer draft on the panel event. */
+export function useBrowserPageContextInsert(setInputValue: DraftSetter): void {
+  const setterRef = useRef(setInputValue);
+  setterRef.current = setInputValue;
+
+  useEffect(() => {
+    const handler = (event: Event): void => {
+      const detail = event instanceof CustomEvent ? event.detail : null;
+      if (!isRecord(detail)) return;
+      const url = readString(detail, 'url');
+      if (!url) return;
+      const title = readString(detail, 'title');
+      setterRef.current((prev) => {
+        const separator = prev && !prev.endsWith('\n') ? '\n\n' : prev ? '\n' : '';
+        const titleLine = title ? `\nJudul: ${title}` : '';
+        return `${prev}${separator}[Konteks halaman browser]\nURL: ${url}${titleLine}\n(Lanjutkan dari halaman ini.)`;
+      });
+    };
+    window.addEventListener(BROWSER_INCLUDE_PAGE_EVENT, handler);
+    return () => window.removeEventListener(BROWSER_INCLUDE_PAGE_EVENT, handler);
+  }, []);
+}

package/src/client/hooks/chat/composer/drop-entries.test.ts

@@ -0,0 +1,234 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reading a drop's payload: the two views of one dragged file, and the
+ * server-side resolution of a reference that carries no bytes.
+ *
+ * The cases here are the ones that fail silently:
+ *
+ * - A drop can expose the SAME file twice — once in `dataTransfer.files`, once
+ *   through the item list — and which of the two objects is readable is not
+ *   knowable up front (a drop that reads in a browser tab has been seen to fail
+ *   in an installed app window, with the failing object still reporting the
+ *   right name and size). Both objects must survive as a pair to try.
+ * - A directory's item entry is not a file to read; it is the tree the walk
+ *   expands. Its `files` counterpart is a size-0, type-less stub.
+ * - A dropped reference has three distinct refusal reasons, and the user can
+ *   only act on the right one.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { readDroppedEntries } from '@/client/hooks/chat/composer/drop-entries';
+import {
+  describeReferenceFailure,
+  describeUnreadable,
+  readDroppedReference,
+  referenceName,
+} from '@/client/hooks/chat/composer/drop-references';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'HTMLElement', 'Element', 'Node', 'Event', 'CustomEvent', 'File', 'Blob'] as const;
+/** The runner's own globals, restored on teardown so later files still have them. */
+const native: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+/** The runner's own fetch, put back on teardown — deleting it strips the global every later file needs. *//** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+const nativeFetch = Bun.fetch;
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in native)) native[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (native[key] === undefined) delete target[key];
+    else target[key] = native[key];
+  }
+  if (nativeFetch) target.fetch = nativeFetch;
+  else delete target.fetch;
+});
+
+afterEach(() => {
+  if (nativeFetch) (globalThis as unknown as Record<string, unknown>).fetch = nativeFetch;
+});
+
+/** A DataTransfer exposing the same item list shape the browser does. */
+function transfer(
+  items: { entry?: FileSystemEntry | null; file?: File | null }[],
+  files: File[] = [],
+): { dt: DataTransfer; getAsFileCalls: () => number } {
+  let calls = 0;
+  const dt = {
+    items: items.map(({ entry = null, file = null }) => ({
+      kind: 'file',
+      webkitGetAsEntry: () => entry,
+      getAsFile: () => { calls += 1; return file; },
+    })),
+    files,
+  } as unknown as DataTransfer;
+  return { dt, getAsFileCalls: () => calls };
+}
+
+function fileEntry(name: string): FileSystemFileEntry {
+  return { isFile: true, isDirectory: false, name } as unknown as FileSystemFileEntry;
+}
+
+describe('readDroppedEntries', () => {
+  test('pairs the two views of one file so a read can fall back to the other', () => {
+    const fromFiles = new File(['bytes'], 'a.ts', { type: 'text/plain' });
+    const fromItems = new File(['bytes'], 'a.ts', { type: 'text/plain' });
+    const { dt } = transfer([{ entry: fileEntry('a.ts'), file: fromItems }], [fromFiles]);
+
+    const entries = readDroppedEntries(dt);
+    expect(entries.files).toEqual([fromFiles]);
+    expect(entries.fallbacks.get(fromFiles)).toBe(fromItems);
+    expect(entries.fallbacks.size).toBe(1);
+  });
+
+  test('does not pair files whose names differ — the name is all they share', () => {
+    const fromFiles = new File(['bytes'], 'a.ts', { type: 'text/plain' });
+    const other = new File(['bytes'], 'b.ts', { type: 'text/plain' });
+    const { dt } = transfer([{ entry: fileEntry('b.ts'), file: other }], [fromFiles]);
+
+    expect(readDroppedEntries(dt).fallbacks.size).toBe(0);
+  });
+
+  test('a directory item is collected for the walk and its file is never read', () => {
+    const directory = { isFile: false, isDirectory: true, name: 'src' } as unknown as FileSystemDirectoryEntry;
+    const { dt, getAsFileCalls } = transfer([{ entry: directory, file: new File(['x'], 'src', { type: '' }) }]);
+
+    const entries = readDroppedEntries(dt);
+    expect(entries.directories).toEqual([directory]);
+    expect(entries.files).toEqual([]);
+    // The entry is read first and in the same pass; consuming the item's other
+    // view afterwards would lose one of the two.
+    expect(getAsFileCalls()).toBe(0);
+  });
+
+  test('a size-0, type-less item stub is not a file to attach', () => {
+    const { dt } = transfer([{ entry: null, file: new File([], 'from-a-page.txt', { type: '' }) }]);
+    expect(readDroppedEntries(dt).files).toEqual([]);
+  });
+
+  test('an item file with no entry is taken as the primary when files is empty', () => {
+    const fromItems = new File(['item body'], 'only-items.txt', { type: 'text/plain' });
+    const { dt } = transfer([{ entry: null, file: fromItems }]);
+    expect(readDroppedEntries(dt).files).toEqual([fromItems]);
+  });
+
+  test('an empty payload yields nothing at all', () => {
+    const { dt } = transfer([]);
+    expect(readDroppedEntries(dt)).toEqual({ files: [], directories: [], fallbacks: new Map() });
+  });
+});
+
+/** A fetch stub answering one canned response, recording the URL it was asked for. */
+function stubFetch(answer: { ok: boolean; status: number; body: unknown } | 'network-error'): { urls: string[] } {
+  const urls: string[] = [];
+  (globalThis as unknown as Record<string, unknown>).fetch = (async (input: unknown) => {
+    urls.push(String(input));
+    if (answer === 'network-error') throw new Error('offline');
+    return { ok: answer.ok, status: answer.status, json: async () => answer.body };
+  }) as unknown as typeof fetch;
+  return { urls };
+}
+
+describe('readDroppedReference', () => {
+  test('a readable reference becomes a text File named by the server', async () => {
+    const { urls } = stubFetch({ ok: true, status: 200, body: { content: '# hello', name: 'notes.md' } });
+
+    const result = await readDroppedReference('/repo/notes.md', '/repo');
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.file.name).toBe('notes.md');
+    expect(result.file.type).toBe('text/plain');
+    expect(await result.file.text()).toBe('# hello');
+    // The root is a hint for a relative reference; the path always travels.
+    expect(urls[0]).toBe('/api/fs/read-reference?path=%2Frepo%2Fnotes.md&root=%2Frepo');
+  });
+
+  test('an absolute reference with no workspace root sends no root hint', async () => {
+    const { urls } = stubFetch({ ok: true, status: 200, body: { content: 'x' } });
+    await readDroppedReference('https://x.example/f.txt', null);
+    expect(urls[0]).toBe('/api/fs/read-reference?path=https%3A%2F%2Fx.example%2Ff.txt');
+  });
+
+  test('the server name wins, and the reference name is the fallback', async () => {
+    stubFetch({ ok: true, status: 200, body: { content: 'x', name: '' } });
+    const result = await readDroppedReference('file:///repo/sub/notes.md', null);
+    expect(result.ok && result.file.name).toBe('notes.md');
+  });
+
+  test('each refusal carries the reason the user has to act on', async () => {
+    stubFetch({ ok: false, status: 403, body: { error: 'remote downloads are not supported' } });
+    expect(await readDroppedReference('https://x/y.png', null)).toEqual({ ok: false, reason: 'remote' });
+
+    stubFetch({ ok: false, status: 415, body: { error: 'not an image or raw text' } });
+    expect(await readDroppedReference('/repo/a.bin', null)).toEqual({ ok: false, reason: 'binary' });
+
+    stubFetch({ ok: false, status: 404, body: { error: 'not found' } });
+    expect(await readDroppedReference('/etc/passwd', null)).toEqual({ ok: false, reason: 'outside-roots' });
+
+    stubFetch({ ok: false, status: 500, body: { error: 'boom' } });
+    expect(await readDroppedReference('/repo/a.ts', null)).toEqual({ ok: false, reason: 'unavailable' });
+  });
+
+  test('a dropped connection and a bodyless 200 are both unavailable', async () => {
+    stubFetch('network-error');
+    expect(await readDroppedReference('/repo/a.ts', null)).toEqual({ ok: false, reason: 'unavailable' });
+
+    stubFetch({ ok: true, status: 200, body: { content: 42 } });
+    expect(await readDroppedReference('/repo/a.ts', null)).toEqual({ ok: false, reason: 'unavailable' });
+  });
+});
+
+describe('referenceName', () => {
+  test('takes the last path segment, decoded, with the query stripped', () => {
+    expect(referenceName('https://x.example/a/my%20notes.md?token=1#frag')).toBe('my notes.md');
+    expect(referenceName('/repo/sub/dir/')).toBe('dir');
+    expect(referenceName('file:///repo/a.ts')).toBe('a.ts');
+  });
+
+  test('falls back to a generic name when there is no segment to take', () => {
+    expect(referenceName('')).toBe('attachment');
+    expect(referenceName('https://x.example')).toBe('x.example');
+  });
+
+  test('a malformed percent-escape keeps the raw segment instead of throwing', () => {
+    expect(referenceName('/repo/%E0%A4%A')).toBe('%E0%A4%A');
+  });
+});
+
+describe('refusal messages', () => {
+  test('name one file or count many', () => {
+    expect(describeUnreadable(['a.md'])).toBe('"a.md" could not be read and was not attached.');
+    expect(describeUnreadable(['a.md', 'b.md'])).toBe('2 files could not be read and were not attached: a.md, b.md.');
+  });
+
+  test('elide the list past three names but keep the count', () => {
+    const many = ['a', 'b', 'c', 'd', 'e'];
+    expect(describeUnreadable(many)).toBe('5 files could not be read and were not attached: a, b, c….');
+    expect(describeReferenceFailure(many, 'binary')).toBe('5 files are not a text file and were not attached (a, b, c…).');
+  });
+
+  test('give each cause its own wording, singular or plural', () => {
+    expect(describeReferenceFailure(['/repo/a.ts'], 'outside-roots'))
+      .toBe('"/repo/a.ts" lies outside the folders Kabmo may read, so it was not attached (/repo/a.ts).');
+    expect(describeReferenceFailure(['a', 'b'], 'outside-roots'))
+      .toBe('2 files lie outside the folders Kabmo may read, so they were not attached (a, b).');
+    expect(describeReferenceFailure(['x.txt'], 'remote'))
+      .toBe('"x.txt" is a web download; save it into a workspace folder first (x.txt).');
+    expect(describeReferenceFailure(['x.txt'], 'binary'))
+      .toBe('"x.txt" is not a text file and was not attached (x.txt).');
+    // An unknown cause degrades to the generic unreadable message.
+    expect(describeReferenceFailure(['x.txt'], 'unavailable'))
+      .toBe('"x.txt" could not be read and was not attached.');
+  });
+});

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

@@ -0,0 +1,204 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Turning a `DataTransfer` into the flat list of `File`s a drop attaches.
+ *
+ * Split out of `file-drop.ts`, which owns the event wiring: everything here is
+ * about reading the payload, and it is the part with the browser rules worth
+ * documenting.
+ *
+ * Two rules, both of which produced a bug when ignored:
+ *
+ * 1. 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.
+ * 2. `getAsFile()` and `webkitGetAsEntry()` are read from the SAME item, and on
+ *    a file-manager drag each call can consume state the other needs — so the
+ *    item list is read exactly ONCE, capturing both views in a single pass.
+ *
+ * The `File`s this returns are only as good as the tick they were captured in:
+ * a dropped file's read permission is released when the drop handler returns,
+ * so `file-drop.ts` primes the reads before awaiting anything. See `file-reads.ts`.
+ */
+
+/**
+ * Safety valve: a dropped tree (a repo root, `node_modules`) must not queue
+ * thousands of attachments. The walk stops as soon as it is reached.
+ */
+export const MAX_DROPPED_FILES = 50;
+
+/** Directory nesting limit — a symlinked cycle would otherwise never end. */
+export const MAX_DROP_DEPTH = 10;
+
+function readEntryFile(entry: FileSystemFileEntry): Promise<File | null> {
+  const { promise, resolve } = Promise.withResolvers<File | null>();
+  entry.file(resolve, () => resolve(null));
+  return promise;
+}
+
+/** `readEntries` yields at most 100 children per call; keep pulling until empty. */
+function readAllEntries(reader: FileSystemDirectoryReader): Promise<FileSystemEntry[]> {
+  const { promise, resolve } = Promise.withResolvers<FileSystemEntry[]>();
+  const all: FileSystemEntry[] = [];
+  const readBatch = () => {
+    reader.readEntries((batch) => {
+      if (batch.length === 0) {
+        resolve(all);
+        return;
+      }
+      all.push(...batch);
+      readBatch();
+    }, () => resolve(all));
+  };
+  readBatch();
+  return promise;
+}
+
+/** Walk one directory tree into `out`; true when a cap stopped the walk early. */
+async function walkDirectory(
+  directory: FileSystemDirectoryEntry,
+  out: File[],
+  depth: number,
+): Promise<boolean> {
+  if (depth >= MAX_DROP_DEPTH) return true;
+  const children = await readAllEntries(directory.createReader());
+  for (const child of children) {
+    if (out.length >= MAX_DROPPED_FILES) return true;
+    if (child.isFile) {
+      const file = await readEntryFile(child as FileSystemFileEntry);
+      if (file) out.push(file);
+    } else if (child.isDirectory) {
+      if (await walkDirectory(child as FileSystemDirectoryEntry, out, depth + 1)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The two views of a drop's item list, captured in ONE pass.
+ *
+ * `getAsFile()` and `webkitGetAsEntry()` must both be read from the same item,
+ * and on a file-manager drag each call can consume state the other needs. Two
+ * separate loops over `items` therefore lose one of them; this captures both
+ * while the item is still fresh.
+ *
+ * `dataTransfer.files` is the PREFERRED source of the `File` objects, not the
+ * item list. On a file-manager drag the two are not interchangeable: the item
+ * entry can carry correct metadata (name, size) over a backing store that no
+ * longer reads, while `files` hands over one that does. Preferring the item list
+ * produced a chip with the right name and size whose contents never arrived, and
+ * the failure survived every retry because the object itself was unreadable.
+ * `files` is also what the working reference implementations read first.
+ *
+ * The item list still earns its place: it is the ONLY way to see a dropped
+ * DIRECTORY (`files` carries a size-0 stub for one), and it is the fallback for
+ * a host that populates only `items`.
+ */
+export interface DroppedEntries {
+  /** Real `File` objects, stubs excluded when a better entry exists. */
+  files: File[];
+  /** Directory entries, for the recursive walk. */
+  directories: FileSystemDirectoryEntry[];
+  /**
+   * The other `File` object for the same dropped file, when the payload exposed
+   * it twice — once through `dataTransfer.files`, once through the item list.
+   *
+   * Which of the two is readable is not knowable up front and differs by
+   * context: a drop that reads fine in a browser tab has been observed to fail
+   * in an installed app window, with the failing object still reporting the
+   * correct name and size. So this is a pair to try, not a preference to settle,
+   * and the read path falls back to this entry when the primary yields nothing.
+   */
+  fallbacks: Map<File, File>;
+}
+
+export function readDroppedEntries(dt: DataTransfer): DroppedEntries {
+  const itemFiles: File[] = [];
+  const directories: FileSystemDirectoryEntry[] = [];
+
+  for (const item of Array.from(dt.items ?? [])) {
+    if (item.kind !== 'file') continue;
+    // Order matters: the entry first, then the file, in the same iteration.
+    const entry = typeof item.webkitGetAsEntry === 'function' ? item.webkitGetAsEntry() : null;
+    if (entry?.isDirectory) {
+      directories.push(entry as FileSystemDirectoryEntry);
+      continue;
+    }
+    const file = typeof item.getAsFile === 'function' ? item.getAsFile() : null;
+    // A directory arrives as a 0-byte, type-less stub; it is not a file to read.
+    if (file && (file.size > 0 || file.type !== '')) itemFiles.push(file);
+  }
+
+  const direct = Array.from(dt.files ?? []);
+  const directWithBytes = direct.filter((file) => file.size > 0);
+  const itemsWithBytes = itemFiles.filter((file) => file.size > 0);
+
+  // `files` first, then the item list, then whatever exists. Every step keeps
+  // the counterpart as a fallback so a read can try the other object rather than
+  // depend on this choice being the right one.
+  if (directWithBytes.length > 0) {
+    return { files: directWithBytes, directories, fallbacks: pairByName(directWithBytes, itemFiles) };
+  }
+  if (itemsWithBytes.length > 0) {
+    return { files: itemsWithBytes, directories, fallbacks: pairByName(itemsWithBytes, direct) };
+  }
+  if (itemFiles.length > 0) {
+    return { files: itemFiles, directories, fallbacks: pairByName(itemFiles, direct) };
+  }
+  return { files: direct, directories, fallbacks: new Map() };
+}
+
+/**
+ * Pair each primary file with its counterpart of the same name, so the read path
+ * has something else to try. Matching is by name because that is all the two
+ * views of one dropped file reliably share.
+ */
+function pairByName(primary: readonly File[], others: readonly File[]): Map<File, File> {
+  const byName = new Map<string, File>();
+  for (const file of others) {
+    if (!byName.has(file.name)) byName.set(file.name, file);
+  }
+  const pairs = new Map<File, File>();
+  for (const file of primary) {
+    const other = byName.get(file.name);
+    if (other && other !== file) pairs.set(file, other);
+  }
+  return pairs;
+}
+
+/**
+ * Expand a drop into the flat file list the composer attaches: the files it
+ * already carries plus every directory's contents, walked recursively.
+ * `incomplete` reports that a cap cut the drop short, so the composer can say so
+ * instead of silently attaching a prefix.
+ *
+ * Takes the entries rather than the `DataTransfer`: see {@link readDroppedEntries}
+ * for why the item list may only be read once.
+ */
+export async function expandDroppedFiles(
+  entries: DroppedEntries,
+): Promise<{ files: File[]; incomplete: boolean }> {
+  const files: File[] = [...entries.files];
+
+  // No directory in the payload: the flat list is already the answer.
+  if (entries.directories.length === 0) {
+    return { files: files.slice(0, MAX_DROPPED_FILES), incomplete: files.length > MAX_DROPPED_FILES };
+  }
+
+  let incomplete = false;
+  for (const directory of entries.directories) {
+    if (files.length >= MAX_DROPPED_FILES) {
+      incomplete = true;
+      break;
+    }
+    if (await walkDirectory(directory, files, 0)) {
+      incomplete = true;
+      break;
+    }
+  }
+  return { files: files.slice(0, MAX_DROPPED_FILES), incomplete };
+}
+