fix(trees): allow resetPaths with preparedInput and no paths (#917)

* fix(trees): allow resetPaths with preparedInput and no paths

The public types required `paths` on `resetPaths` even when the caller
supplied `preparedInput`, although `resolveFileTreeInput` already
short-circuits when `paths == null && preparedInput != null`. Callers
using `preparePresortedFileTreeInput` were forced to pass a dummy `paths`
list, which `PathStore.preparePaths` then re-parsed and re-sorted — the
exact work the presorted API exists to skip.

Add a preparedInput-only overload to `resetPaths` (on both the public
`FileTreeMutationHandle` and the `FileTreeController`/`FileTree` runtimes)
so exactly one of `paths` or `preparedInput` is required; passing neither
is a type error. Runtime already supported the branch; the implementation
now normalizes the single-argument options form.

Fixes #670

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FDXG4jRZT8sPS1YBSes2pR

* style(trees): wrap long resetPaths delegate line for oxfmt

CI root:format-check (oxfmt) wrapped the single-arg resetPaths delegate
call that exceeded the print width. No behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FDXG4jRZT8sPS1YBSes2pR

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

packages/trees/src/index.ts

@@ -74,6 +74,7 @@ export type {
   FileTreeRenderProps,
   FileTreeResetEvent,
   FileTreeResetOptions,
+  FileTreeResetPreparedOptions,
   FileTreeRowDecoration,
   FileTreeRowDecorationContext,
   FileTreeRowDecorationRenderer,

packages/trees/src/model/FileTreeController.ts

@@ -55,6 +55,7 @@ import type {
   FileTreeRenamingConfig,
   FileTreeResetEvent,
   FileTreeResetOptions,
+  FileTreeResetPreparedOptions,
   FileTreeScrollOffset,
   FileTreeScrollToPathOptions,
   FileTreeSearchMode,
@@ -1252,8 +1253,20 @@ export class FileTreeController
    */
   public resetPaths(
     paths: readonly string[],
-    options: FileTreeResetOptions = {}
+    options?: FileTreeResetOptions
+  ): void;
+  public resetPaths(options: FileTreeResetPreparedOptions): void;
+  public resetPaths(
+    pathsOrOptions: readonly string[] | FileTreeResetPreparedOptions,
+    maybeOptions: FileTreeResetOptions = {}
   ): void {
+    const usingPreparedOnlyOverload = !Array.isArray(pathsOrOptions);
+    const paths = usingPreparedOnlyOverload
+      ? undefined
+      : (pathsOrOptions as readonly string[]);
+    const options: FileTreeResetOptions = usingPreparedOnlyOverload
+      ? (pathsOrOptions as FileTreeResetPreparedOptions)
+      : maybeOptions;
     const previousPathCount = this.#store.list().length;
     const previousVisibleCount = this.#visibleCount;
     const resolvedInput = resolveFileTreeInput(

packages/trees/src/model/publicTypes.ts

@@ -323,16 +323,27 @@ export type FileTreeMutationEventForType<
   ? FileTreeMutationEvent
   : Extract<FileTreeMutationEvent, { operation: TType }>;
 
-export interface FileTreeResetOptions {
+interface FileTreeResetBehaviorOptions {
   // When provided, replaces the baseline expansion set stored at construction
   // time. Useful when the caller is swapping in a dramatically different path
   // list (e.g. upgrading from an SSR preview to a full dataset) and wants the
   // fresh store to start with expansion state that reflects the new paths.
   initialExpandedPaths?: readonly FileTreePublicId[];
-  // Must describe the same path list passed to resetPaths(paths, ...).
-  preparedInput?: FileTreePreparedInput;
 }
 
+export type FileTreeResetOptions = FileTreeResetBehaviorOptions & {
+  // When omitted, the raw `paths` argument describes the tree. When provided,
+  // it must describe the same path list passed to resetPaths(paths, ...).
+  preparedInput?: FileTreePreparedInput;
+};
+
+// Options shape for the preparedInput-only `resetPaths` overload. `paths` may be
+// omitted entirely because `preparedInput` already carries the canonical path
+// list, so the runtime skips the parse + sort that raw `paths` would require.
+export type FileTreeResetPreparedOptions = FileTreeResetBehaviorOptions & {
+  preparedInput: FileTreePreparedInput;
+};
+
 export interface FileTreeMutationHandle {
   add(path: FileTreePublicId): void;
   batch(operations: readonly FileTreeBatchOperation[]): void;
@@ -346,10 +357,14 @@ export interface FileTreeMutationHandle {
     handler: (event: FileTreeMutationEventForType<TType>) => void
   ): () => void;
   remove(path: FileTreePublicId, options?: FileTreeRemoveOptions): void;
+  // Exactly one of `paths` or `preparedInput` is required. Pass raw `paths`
+  // (optionally with a matching `preparedInput`), or pass `preparedInput`
+  // alone to skip the parse + sort that raw `paths` would otherwise require.
   resetPaths(
     paths: readonly FileTreePublicId[],
     options?: FileTreeResetOptions
   ): void;
+  resetPaths(options: FileTreeResetPreparedOptions): void;
 }
 
 export type FileTreeListener = () => void;

packages/trees/src/render/FileTree.ts

@@ -43,6 +43,7 @@ import type {
   FileTreeRemoveOptions,
   FileTreeRenderProps,
   FileTreeResetOptions,
+  FileTreeResetPreparedOptions,
   FileTreeRowDecorationRenderer,
   FileTreeScrollToPathOptions,
   FileTreeSearchSessionHandle,
@@ -438,8 +439,19 @@ export class FileTree
   public resetPaths(
     paths: readonly string[],
     options?: FileTreeResetOptions
+  ): void;
+  public resetPaths(options: FileTreeResetPreparedOptions): void;
+  public resetPaths(
+    pathsOrOptions: readonly string[] | FileTreeResetPreparedOptions,
+    options?: FileTreeResetOptions
   ): void {
-    this.#controller.resetPaths(paths, options);
+    if (Array.isArray(pathsOrOptions)) {
+      this.#controller.resetPaths(pathsOrOptions as readonly string[], options);
+    } else {
+      this.#controller.resetPaths(
+        pathsOrOptions as FileTreeResetPreparedOptions
+      );
+    }
   }
 
   // Deliberately rerenders even when the same object reference is passed again.

packages/trees/test/file-tree-dynamic-files-mutation-api.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, test } from 'bun:test';
 import { JSDOM } from 'jsdom';
 
-import { prepareFileTreeInput } from '../src/index';
+import {
+  prepareFileTreeInput,
+  preparePresortedFileTreeInput,
+} from '../src/index';
 import { flushDom, installDom } from './helpers/dom';
 import { loadFileTree, loadFileTreeController } from './helpers/loadFileTree';
 
@@ -141,6 +144,61 @@ describe('file-tree dynamic files / mutation API', () => {
     controller.destroy();
   });
 
+  test('resetPaths accepts a preparedInput-only call with no raw paths', async () => {
+    const FileTreeController = await loadFileTreeController();
+
+    // Server-canonical (already sorted) folder paths, the scale-oriented input
+    // that preparePresortedFileTreeInput exists to fast-path.
+    const folderPaths = ['src/', 'src/index.ts', 'README.md'] as const;
+    const controller = new FileTreeController({
+      flattenEmptyDirectories: false,
+      initialExpansion: 'open',
+      paths: ['README.md'],
+    });
+
+    // The preparedInput-only overload: no dummy `paths` argument required.
+    controller.resetPaths({
+      preparedInput: preparePresortedFileTreeInput([...folderPaths]),
+    });
+
+    expect(controller.getVisibleRows(0, 3).map((row) => row.path)).toEqual([
+      'src/',
+      'src/index.ts',
+      'README.md',
+    ]);
+
+    controller.destroy();
+  });
+
+  test('resetPaths overloads type-check as documented (compile-only assertions)', async () => {
+    const FileTreeController = await loadFileTreeController();
+
+    const controller = new FileTreeController({
+      flattenEmptyDirectories: false,
+      initialExpansion: 'open',
+      paths: ['README.md'],
+    });
+
+    const assertOverloadTyping = (): void => {
+      // Passing only preparedInput type-checks: `paths` is no longer required.
+      controller.resetPaths({
+        preparedInput: prepareFileTreeInput(['README.md']),
+      });
+
+      // Passing only raw paths still type-checks.
+      controller.resetPaths(['README.md']);
+
+      // @ts-expect-error neither paths nor preparedInput is supplied
+      controller.resetPaths({});
+
+      // @ts-expect-error neither paths nor preparedInput is supplied
+      controller.resetPaths();
+    };
+    void assertOverloadTyping;
+
+    controller.destroy();
+  });
+
   test('typed onMutation listeners stay filtered while subscribe still tracks non-mutation rerenders', async () => {
     const FileTreeController = await loadFileTreeController();