@tablestore/tablestore-agent-cli 0.2.0 → 0.2.1

package/dist/dashboard-runtime/dashboard/src/components/retrieval/assemble-retrieval-configuration.ts

@@ -24,14 +24,33 @@ export function assembleRetrievalConfiguration(
   v: Partial<RetrievalInput>,
   topK: number | undefined,
 ): RetrievalConfiguration | undefined {
-  const reranking = buildRerankingConfiguration(v, topK);
+  const denseTopK = getResultCount(v.denseTopK, v.topK, topK);
+  const fullTextTopK = getResultCount(v.fullTextTopK, v.topK, topK);
+  const rerankTopK = getResultCount(v.rerankTopK, v.topK, topK);
+  const reranking = buildRerankingConfiguration(v, rerankTopK);
   const config: RetrievalConfiguration = {};
   if (v.searchType?.length) config.searchType = v.searchType;
-  if (topK) config.denseVectorSearchConfiguration = { numberOfResults: topK };
+  if (denseTopK !== undefined) {
+    config.denseVectorSearchConfiguration = { numberOfResults: denseTopK };
+  }
+  if (fullTextTopK !== undefined) {
+    config.fullTextSearchConfiguration = { numberOfResults: fullTextTopK };
+  }
   if (reranking) config.rerankingConfiguration = reranking;
   return Object.keys(config).length > 0 ? config : undefined;
 }
 
+function getResultCount(
+  primary: number | undefined,
+  legacyTopK: number | undefined,
+  fallbackTopK: number | undefined,
+): number | undefined {
+  if (typeof primary === "number") return primary;
+  if (typeof legacyTopK === "number") return legacyTopK;
+  if (typeof fallbackTopK === "number") return fallbackTopK;
+  return undefined;
+}
+
 /** Build the nested `rerankingConfiguration` sub-object from flat form fields. */
 function buildRerankingConfiguration(
   v: Partial<RetrievalInput>,
@@ -40,8 +59,8 @@ function buildRerankingConfiguration(
   if (!v.rerankType) return undefined;
   const base: RerankingConfiguration = {
     type: v.rerankType,
-    numberOfResults: topK,
   };
+  if (topK !== undefined) base.numberOfResults = topK;
   if (v.rerankType === "RRF") {
     base.rrfConfiguration = {
       k: v.rrfK,

package/dist/dashboard-runtime/dashboard/src/components/retrieval/retrieval-form.tsx

@@ -56,7 +56,7 @@ export function assembleRetrievalRequest(
   v: RetrievalInput,
   filter: Record<string, unknown> | undefined,
 ): RetrievalRequest {
-  const config = assembleRetrievalConfiguration(v, v.topK) ?? {};
+  const config = assembleRetrievalConfiguration(v, undefined) ?? {};
   if (filter) config.filter = filter;
 
   const req: RetrievalRequest = {
@@ -79,6 +79,8 @@ export function retrievalDefaultsFromKB(
 ): RetrievalInput {
   const kbSearchType = knowledgeBase?.retrievalConfiguration?.searchType ?? ["DENSE_VECTOR"];
   const kbRerank = knowledgeBase?.retrievalConfiguration?.rerankingConfiguration;
+  const kbDense = knowledgeBase?.retrievalConfiguration?.denseVectorSearchConfiguration;
+  const kbFullText = knowledgeBase?.retrievalConfiguration?.fullTextSearchConfiguration;
   const kbRrf = kbRerank?.rrfConfiguration;
   const kbWeight = kbRerank?.weightConfiguration;
   const kbModel = kbRerank?.modelConfiguration;
@@ -92,13 +94,18 @@ export function retrievalDefaultsFromKB(
       : kbRerank?.type === "MODEL"
         ? "MODEL"
         : "WEIGHT";
-  const kbNumberOfResults = kbRerank?.numberOfResults ?? 5;
+  const kbDenseTopK = kbDense?.numberOfResults ?? kbRerank?.numberOfResults ?? 20;
+  const kbFullTextTopK = kbFullText?.numberOfResults ?? kbRerank?.numberOfResults ?? 20;
+  const kbRerankTopK = kbRerank?.numberOfResults ?? 20;
 
   return {
     knowledgeBaseName,
     query: "",
     subspace: [],
-    topK: kbNumberOfResults,
+    topK: kbRerankTopK,
+    denseTopK: kbDenseTopK,
+    fullTextTopK: kbFullTextTopK,
+    rerankTopK: kbRerankTopK,
     searchType: kbSearchType,
     rerankType: kbRerankType,
     rrfK: kbRrf?.k ?? 60,

package/dist/dashboard-runtime/dashboard/src/components/retrieval/retrieval-params-fields.tsx

@@ -4,7 +4,6 @@ import { useEffect, useRef } from "react";
 import type { UseFormReturn } from "react-hook-form";
 import { Check, ChevronDown, HelpCircle, Info } from "lucide-react";
 
-import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
 import { useSubspaceOptional } from "@/contexts/subspace-context";
 import {
@@ -27,6 +26,7 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { TagInput } from "@/components/shared/tag-input";
+import { RetrievalResultCountField } from "@/components/knowledge-base/retrieval-result-count-field";
 import { FilterBuilder, type FilterBuilderHandle } from "./filter-builder";
 import { RetrievalRerankFields } from "./retrieval-rerank-fields";
 import type { RetrievalInput } from "@/schemas/retrieval";
@@ -58,6 +58,7 @@ export interface RetrievalParamsFieldsProps {
    *  label. Used for verbose explanations that would otherwise wrap the
    *  label across multiple lines and break left/right column alignment. */
   topKHint?: string;
+  topKMode?: "split" | "single";
 }
 
 export function RetrievalParamsFields({
@@ -66,11 +67,13 @@ export function RetrievalParamsFields({
   filterRef,
   topKLabel = "返回数量",
   topKHint,
+  topKMode = "split",
 }: RetrievalParamsFieldsProps) {
   const currentSearchType = form.watch("searchType");
+  const denseEnabled = !!currentSearchType?.includes("DENSE_VECTOR");
+  const fullTextEnabled = !!currentSearchType?.includes("FULL_TEXT");
   const hybrid =
-    !!currentSearchType?.includes("DENSE_VECTOR") &&
-    !!currentSearchType?.includes("FULL_TEXT");
+    denseEnabled && fullTextEnabled;
   const metadataFields = knowledgeBase?.metadata ?? [];
 
   // Pre-fill the subspace field with the active scope, but only once per
@@ -114,59 +117,14 @@ export function RetrievalParamsFields({
         />
       )}
 
-      <div className="grid gap-4 sm:grid-cols-2">
-        <FormField
-          control={form.control}
-          name="topK"
-          render={({ field }) => (
-            <FormItem className="space-y-1.5">
-              <div className="flex items-center gap-1">
-                <FormLabel className="leading-tight">{topKLabel}</FormLabel>
-                {topKHint ? (
-                  <TooltipProvider delayDuration={150}>
-                    <Tooltip>
-                      <TooltipTrigger asChild>
-                        <button
-                          type="button"
-                          tabIndex={-1}
-                          aria-label="字段说明"
-                          className="inline-flex h-5 w-5 items-center justify-center rounded text-muted-foreground/60 transition-colors hover:bg-[hsl(var(--muted))] hover:text-foreground"
-                        >
-                          <HelpCircle className="h-3.5 w-3.5" />
-                        </button>
-                      </TooltipTrigger>
-                      <TooltipContent
-                        side="top"
-                        sideOffset={6}
-                        className="z-[60] max-w-[240px] border border-[hsl(var(--border))] bg-[hsl(var(--popover))] px-3 py-2 text-xs leading-relaxed text-[hsl(var(--popover-foreground))] shadow-md"
-                      >
-                        {topKHint}
-                      </TooltipContent>
-                    </Tooltip>
-                  </TooltipProvider>
-                ) : null}
-              </div>
-              <FormControl>
-                <Input
-                  type="number"
-                  min={1}
-                  max={100}
-                  className="h-9"
-                  {...field}
-                  onChange={(event) =>
-                    field.onChange(
-                      event.target.value
-                        ? Number(event.target.value)
-                        : undefined,
-                    )
-                  }
-                />
-              </FormControl>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-
+      <div className={topKMode === "single" ? "grid gap-4 sm:grid-cols-2" : "space-y-4"}>
+        {topKMode === "single" ? (
+          <TopKNumberField
+            form={form}
+            label={topKLabel}
+            hint={topKHint}
+          />
+        ) : null}
         <FormField
           control={form.control}
           name="searchType"
@@ -202,6 +160,44 @@ export function RetrievalParamsFields({
         />
       </div>
 
+      {topKMode === "split" ? (
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <p className="text-sm font-medium text-[hsl(var(--foreground))]">
+              返回数量
+            </p>
+            <p className="text-xs text-[hsl(var(--muted-foreground))]">
+              控制每路召回参与排序的候选数，以及 Rerank 后实际返回的片段数。
+            </p>
+          </div>
+          <div className="grid grid-cols-[repeat(auto-fit,minmax(min(260px,100%),1fr))] gap-3">
+            <RetrievalResultCountField
+              control={form.control}
+              name="denseTopK"
+              label="向量召回数"
+              description="向量检索参与后续排序的候选片段数。"
+              max={100}
+              muted={!denseEnabled}
+            />
+            <RetrievalResultCountField
+              control={form.control}
+              name="fullTextTopK"
+              label="全文召回数"
+              description="全文检索参与后续排序的候选片段数。"
+              max={100}
+              muted={!fullTextEnabled}
+            />
+          </div>
+          <RetrievalResultCountField
+            control={form.control}
+            name="rerankTopK"
+            label="重排序返回数"
+            description="Rerank 后保留并返回的片段数。"
+            max={200}
+          />
+        </div>
+      ) : null}
+
       <div className="space-y-2">
         <FormField
           control={form.control}
@@ -279,3 +275,65 @@ export function RetrievalParamsFields({
     </>
   );
 }
+
+function TopKNumberField({
+  form,
+  label,
+  hint,
+}: {
+  form: UseFormReturn<RetrievalInput>;
+  label: string;
+  hint?: string;
+}) {
+  return (
+    <FormField
+      control={form.control}
+      name="topK"
+      render={({ field }) => (
+        <FormItem className="space-y-1.5">
+          <div className="flex items-center gap-1">
+            <FormLabel className="leading-tight">{label}</FormLabel>
+            {hint ? (
+              <TooltipProvider delayDuration={150}>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <button
+                      type="button"
+                      tabIndex={-1}
+                      aria-label="字段说明"
+                      className="inline-flex h-5 w-5 items-center justify-center rounded text-muted-foreground/60 transition-colors hover:bg-[hsl(var(--muted))] hover:text-foreground"
+                    >
+                      <HelpCircle className="h-3.5 w-3.5" />
+                    </button>
+                  </TooltipTrigger>
+                  <TooltipContent
+                    side="top"
+                    sideOffset={6}
+                    className="z-[60] max-w-[240px] border border-[hsl(var(--border))] bg-[hsl(var(--popover))] px-3 py-2 text-xs leading-relaxed text-[hsl(var(--popover-foreground))] shadow-md"
+                  >
+                    {hint}
+                  </TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+            ) : null}
+          </div>
+          <FormControl>
+            <input
+              type="number"
+              min={0}
+              max={100}
+              className="flex h-9 w-full rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--card))] px-3 py-1 text-sm transition-colors focus-visible:border-[hsl(var(--primary))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary)/0.2)]"
+              {...field}
+              onChange={(event) =>
+                field.onChange(
+                  event.target.value ? Number(event.target.value) : undefined,
+                )
+              }
+            />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}

package/dist/dashboard-runtime/dashboard/src/hooks/use-detail-sidebar-collapsed.ts

@@ -0,0 +1,86 @@
+"use client";
+
+import { useCallback, useSyncExternalStore } from "react";
+
+/**
+ * Mirror of {@link useSidebarCollapsed} for the *secondary* (detail-page)
+ * sidebar. Same persistence + cross-instance + cross-tab sync pattern, with
+ * a separate localStorage key so the two sidebars collapse independently.
+ *
+ * The reason for two hooks rather than one with a key parameter: each
+ * useSyncExternalStore needs a stable subscribe / snapshot pair, and a
+ * single subscribe shared between two state slots would notify all
+ * consumers on every change. Splitting keeps the dependency graph clean
+ * and avoids the "primary toggle re-renders every detail page" gotcha.
+ */
+const STORAGE_KEY = "detail-sidebar.collapsed";
+const EVENT_NAME = "detail-sidebar-collapsed-change";
+
+let cachedValue: boolean | null = null;
+
+function readFromStorage(): boolean {
+  if (cachedValue !== null) return cachedValue;
+  if (typeof window === "undefined") {
+    cachedValue = false;
+    return false;
+  }
+  try {
+    cachedValue = window.localStorage.getItem(STORAGE_KEY) === "1";
+  } catch {
+    cachedValue = false;
+  }
+  return cachedValue;
+}
+
+function subscribe(notify: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  const handler = (event: Event) => {
+    const detail = (event as CustomEvent<boolean>).detail;
+    cachedValue = Boolean(detail);
+    notify();
+  };
+  const onStorage = (event: StorageEvent) => {
+    if (event.key !== STORAGE_KEY) return;
+    cachedValue = event.newValue === "1";
+    notify();
+  };
+  window.addEventListener(EVENT_NAME, handler as EventListener);
+  window.addEventListener("storage", onStorage);
+  return () => {
+    window.removeEventListener(EVENT_NAME, handler as EventListener);
+    window.removeEventListener("storage", onStorage);
+  };
+}
+
+function getSnapshot(): boolean {
+  return readFromStorage();
+}
+
+// During SSR the detail sidebar starts expanded; hydration reconciles.
+function getServerSnapshot(): boolean {
+  return false;
+}
+
+export function useDetailSidebarCollapsed() {
+  const collapsed = useSyncExternalStore(
+    subscribe,
+    getSnapshot,
+    getServerSnapshot,
+  );
+
+  const setCollapsed = useCallback((next: boolean) => {
+    cachedValue = next;
+    try {
+      window.localStorage.setItem(STORAGE_KEY, next ? "1" : "0");
+    } catch {
+      // Ignore — private mode / quota / etc.
+    }
+    window.dispatchEvent(new CustomEvent(EVENT_NAME, { detail: next }));
+  }, []);
+
+  const toggle = useCallback(() => {
+    setCollapsed(!readFromStorage());
+  }, [setCollapsed]);
+
+  return { collapsed, setCollapsed, toggle };
+}

package/dist/dashboard-runtime/dashboard/src/hooks/use-oss-import.ts

@@ -0,0 +1,148 @@
+import { useCallback, useState } from "react";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import {
+  addDocuments,
+  UPLOAD_TIMEOUT_MS,
+  type AddDocumentItem,
+  type DocumentOperationResult,
+} from "@/services/documents";
+import { invalidateKnowledgeBaseQueries } from "@/lib/query-keys";
+
+export interface OssImportProgress {
+  phase: "upload" | "done";
+  totalItems: number;
+  completedItems: number;
+  errors: string[];
+}
+
+interface OssImportVariables {
+  knowledgeBaseName: string;
+  /** ossKeys for individually-checked files. Submitted as-is, no filters. */
+  fileKeys: string[];
+  /** Folder prefixes (ending with `/`). Server recurses; filters apply. */
+  folderPrefixes: string[];
+  /** Glob arrays produced by `lib/glob-filter.ts`. Sent to the server only
+   *  on folder items — file items don't carry filters. */
+  inclusionFilters?: string[];
+  exclusionFilters?: string[];
+  subspace?: string;
+  metadata?: Record<string, unknown>;
+}
+
+const SUBMISSION_BATCH_SIZE = 10; // matches services/documents.ts BATCH_SIZE
+
+/**
+ * Submit an OSS-mode import to the KB.
+ *
+ * The KB API natively accepts a folder ossKey (`oss://<bucket>/docs/2026/`)
+ * and recurses on the server side, so the client doesn't need to expand
+ * folders into individual keys. Each {@link OssSelection} item becomes one
+ * `AddDocumentItem`:
+ *
+ *   - file selection   → `{ ossKey }`                    (no filters)
+ *   - folder selection → `{ ossKey, inclusionFilters?, exclusionFilters? }`
+ *
+ * The full document list is submitted via `addDocuments`, which already
+ * handles `BATCH_SIZE` chunking internally. We re-batch here only because
+ * we want incremental progress — `addDocuments` doesn't expose a callback.
+ *
+ * Per-batch failures are tolerated: surviving batches' results are kept and
+ * the failed slice is recorded as `status: "failed"` per ossKey. This
+ * mirrors `useUploadDocuments`'s tolerance for partial-failure import.
+ */
+export function useOssImport() {
+  const queryClient = useQueryClient();
+  const [progress, setProgress] = useState<OssImportProgress | null>(null);
+
+  const resetProgress = useCallback(() => setProgress(null), []);
+
+  const mutation = useMutation({
+    mutationFn: async (vars: OssImportVariables) => {
+      // Build the AddDocumentItem list. Filters attach only to folder items —
+      // a checked file is an explicit user intent and bypasses include/exclude
+      // (matches the local-folder semantics).
+      const items: AddDocumentItem[] = [
+        ...vars.fileKeys.map<AddDocumentItem>((ossKey) => ({
+          ossKey,
+          ...(vars.metadata ? { metadata: vars.metadata } : {}),
+        })),
+        ...vars.folderPrefixes.map<AddDocumentItem>((ossKey) => ({
+          ossKey,
+          ...(vars.metadata ? { metadata: vars.metadata } : {}),
+          ...(vars.inclusionFilters
+            ? { inclusionFilters: vars.inclusionFilters }
+            : {}),
+          ...(vars.exclusionFilters
+            ? { exclusionFilters: vars.exclusionFilters }
+            : {}),
+        })),
+      ];
+
+      if (items.length === 0) {
+        setProgress({ phase: "done", totalItems: 0, completedItems: 0, errors: [] });
+        return { documentDetails: [] as DocumentOperationResult[] };
+      }
+
+      setProgress({
+        phase: "upload",
+        totalItems: items.length,
+        completedItems: 0,
+        errors: [],
+      });
+
+      const allResults: DocumentOperationResult[] = [];
+      const allErrors: string[] = [];
+      for (let i = 0; i < items.length; i += SUBMISSION_BATCH_SIZE) {
+        const slice = items.slice(i, i + SUBMISSION_BATCH_SIZE);
+        try {
+          const resp = await addDocuments(
+            {
+              knowledgeBaseName: vars.knowledgeBaseName,
+              subspace: vars.subspace,
+              documents: slice,
+            },
+            { timeoutMs: UPLOAD_TIMEOUT_MS },
+          );
+          allResults.push(...resp.documentDetails);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          allErrors.push(`批次 ${Math.floor(i / SUBMISSION_BATCH_SIZE) + 1}: ${message}`);
+          for (const item of slice) {
+            allResults.push({
+              ossKey: item.ossKey,
+              status: "failed",
+              failureReason: message,
+            });
+          }
+        }
+        setProgress((p) =>
+          p
+            ? {
+                ...p,
+                completedItems: Math.min(p.totalItems, p.completedItems + slice.length),
+              }
+            : p,
+        );
+      }
+
+      setProgress({
+        phase: "done",
+        totalItems: items.length,
+        completedItems: items.length,
+        errors: allErrors,
+      });
+      return { documentDetails: allResults };
+    },
+    onSuccess: () => {
+      invalidateKnowledgeBaseQueries(queryClient);
+    },
+    onSettled: () => {
+      // Match the local upload hook's "linger briefly so the user reads the
+      // final state" gesture before clearing.
+      setTimeout(resetProgress, 300);
+    },
+  });
+
+  return { ...mutation, progress };
+}

package/dist/dashboard-runtime/dashboard/src/hooks/use-oss-list.ts

@@ -0,0 +1,89 @@
+import { useInfiniteQuery } from "@tanstack/react-query";
+
+import {
+  listOssObjects,
+  type OssListFile,
+  type OssListFolder,
+  type OssListPage,
+} from "@/services/oss";
+
+interface UseOssListOptions {
+  prefix: string;
+  search?: string;
+  /** When false, pauses fetching — useful while the parent tab is hidden. */
+  enabled?: boolean;
+}
+
+export interface UseOssListResult {
+  folders: OssListFolder[];
+  files: OssListFile[];
+  isLoading: boolean;
+  isFetchingNextPage: boolean;
+  hasNextPage: boolean;
+  fetchNextPage: () => void;
+  refetch: () => void;
+  error: Error | null;
+  /** Forwarded so the UI can render the "OSS_FORBIDDEN / NOT_CONFIGURED" state. */
+  errorCode: string | null;
+}
+
+const PAGE_SIZE = 100;
+
+/**
+ * Query key shape mirrors `lib/query-keys.ts` conventions: a stable string
+ * head plus the variable identifiers. Co-located with the hook because no
+ * other module needs to invalidate this cache (the page is read-only).
+ */
+function queryKey(prefix: string, search: string) {
+  return ["oss-list", prefix, search] as const;
+}
+
+export function useOssList(options: UseOssListOptions): UseOssListResult {
+  const { prefix, search = "", enabled = true } = options;
+
+  const query = useInfiniteQuery<OssListPage, Error>({
+    queryKey: queryKey(prefix, search),
+    queryFn: ({ pageParam }) =>
+      listOssObjects({
+        prefix,
+        continuationToken: typeof pageParam === "string" ? pageParam : undefined,
+        maxResults: PAGE_SIZE,
+        search: search || undefined,
+      }),
+    getNextPageParam: (last) => last.nextContinuationToken ?? undefined,
+    initialPageParam: undefined,
+    enabled,
+    // Listings are invalidated by re-mounting the dialog, not by mutations.
+    staleTime: 30_000,
+    refetchOnWindowFocus: false,
+  });
+
+  const folders: OssListFolder[] = [];
+  const files: OssListFile[] = [];
+  for (const page of query.data?.pages ?? []) {
+    folders.push(...page.folders);
+    files.push(...page.files);
+  }
+
+  // Surface error code from the standard envelope so the UI can switch on it.
+  const errorCode =
+    query.error && typeof query.error === "object" && "code" in query.error
+      ? String((query.error as { code: unknown }).code ?? "")
+      : null;
+
+  return {
+    folders,
+    files,
+    isLoading: query.isLoading,
+    isFetchingNextPage: query.isFetchingNextPage,
+    hasNextPage: Boolean(query.hasNextPage),
+    fetchNextPage: () => {
+      if (query.hasNextPage && !query.isFetchingNextPage) query.fetchNextPage();
+    },
+    refetch: () => {
+      void query.refetch();
+    },
+    error: query.error ?? null,
+    errorCode,
+  };
+}

package/dist/dashboard-runtime/dashboard/src/lib/extension-filter.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared filename-extension and recursion rules used by both the local-folder
+ * upload mode and the server-side OSS prefix expansion. Keeping the rule shape
+ * and matching logic in one place is what guarantees the two paths agree.
+ *
+ * `include` / `exclude` are lowercase, dotted suffixes ([".md", ".pdf"]).
+ * They apply to the file's basename, not to its path — directory names never
+ * count toward the suffix check.
+ */
+export interface ExtensionRules {
+  include: string[];
+  exclude: string[];
+}
+
+export interface RecursiveExtensionRules extends ExtensionRules {
+  recursive: boolean;
+}
+
+/**
+ * Normalize a comma-separated extension list like ".md, pdf , .TXT" into a
+ * lowercase, dot-prefixed array: [".md", ".pdf", ".txt"]. Empty tokens are
+ * dropped; missing leading dots are added.
+ */
+export function parseExtensionList(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean)
+    .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
+}
+
+/** Pure name-based check. No path or depth involved — caller handles those. */
+export function matchesExtension(name: string, rules: ExtensionRules): boolean {
+  const lower = name.toLowerCase();
+  if (rules.include.length > 0 && !rules.include.some((ext) => lower.endsWith(ext))) {
+    return false;
+  }
+  if (rules.exclude.length > 0 && rules.exclude.some((ext) => lower.endsWith(ext))) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Filter a File[] picked through `<input webkitdirectory>` or drag-drop.
+ *
+ * The `webkitRelativePath` shape is "<root>/<...subpath>", so the top-level
+ * file inside the picked folder lives at depth 1. That's why the recursive
+ * cutoff here is `depth > 1` — anything deeper is a subdirectory.
+ */
+export function filterFolderFiles(
+  files: File[],
+  rules: RecursiveExtensionRules,
+): File[] {
+  return files.filter((file) => {
+    const rel = file.webkitRelativePath || file.name;
+    const depth = (rel.match(/\//g) || []).length;
+    if (!rules.recursive && depth > 1) return false;
+    return matchesExtension(file.name, rules);
+  });
+}
+