@ziioapp/finder 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ziioai
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @ziioapp/finder
+
+使用 `@ziioapp/ui` 构建的可嵌入式多窗口 Finder。UI 不绑定 OPFS；应用通过 `FsBackend` 接入任意文件源。
+
+```tsx
+import { FinderDesktop, createFinderStore, type FsBackend } from "@ziioapp/finder";
+
+const finder = createFinderStore("my-files");
+
+export function FilesPage({ backend }: { backend: FsBackend }) {
+  return <FinderDesktop backend={backend} api={finder} />;
+}
+```
+
+应用须安装兼容版本的 React 与 `@ziioapp/ui`，并在应用根部挂载 `@ziioapp/ui` 所需的反馈展示组件。Finder 内部使用 `notify` 显示操作结果。
+
+Tailwind 4 源码编译模式下，在应用的全局 CSS 中加入一次：
+
+```css
+@import "@ziioapp/ui/styles/source.css";
+@import "@ziioapp/finder/styles/source.css";
+```
+
+应用还需提供自身的主题 CSS 与 Tailwind 扫描入口。Finder 样式使用 `@ziioapp/ui` 的语义 token，不附带独立主题。它是浏览器端交互组件；SSR／SSG 环境应只在客户端初始化窗口状态与文件后端。
+
+`WindowFrame` 可从根入口或 `/window-frame` 子路径单独导入。`createFinderStore(scope)` 的视图模式仍沿用 `flaredrive-finder-viewmode-${scope}` 本地存储键，迁移现有应用时不会清除偏好。`DriveItem.path` 使用无前导斜杠的相对路径，具体后端负责转换。
+
+编写独立后端时，可从 `/backend`、`/types` 导入协议类型，从 `/format` 导入无需加载 React UI 的格式工具。

package/dist/async-state.d.ts

@@ -0,0 +1,21 @@
+export type AsyncState<T, TError = Error> = {
+    status: "idle";
+} | {
+    status: "loading";
+    previous?: T;
+} | {
+    status: "ready";
+    data: T;
+} | {
+    status: "empty";
+    data: T;
+} | {
+    status: "error";
+    error: TError;
+    previous?: T;
+} | {
+    status: "forbidden";
+    reason?: string;
+};
+export declare function asyncStateData<T, TError>(state: AsyncState<T, TError>): T | undefined;
+export declare function settleAsyncState<T>(data: T, isEmpty: (data: T) => boolean): AsyncState<T>;

package/dist/async-state.js

@@ -0,0 +1,15 @@
+export function asyncStateData(state) {
+    switch (state.status) {
+        case "ready":
+        case "empty":
+            return state.data;
+        case "loading":
+        case "error":
+            return state.previous;
+        default:
+            return undefined;
+    }
+}
+export function settleAsyncState(data, isEmpty) {
+    return isEmpty(data) ? { status: "empty", data } : { status: "ready", data };
+}

package/dist/backend.d.ts

@@ -0,0 +1,35 @@
+import type { DriveItem } from "./types.js";
+export interface DriveListing {
+    items: DriveItem[];
+    fromCache: boolean;
+    cachedAt?: number;
+}
+export interface ReadResult {
+    blob: Blob;
+    fromCache: boolean;
+}
+export interface FsCapabilities {
+    upload: boolean;
+    mkdir: boolean;
+    rename: boolean;
+    remove: boolean;
+    cache: boolean;
+}
+export interface ReadOptions {
+    forceFresh?: boolean;
+}
+export interface FsBackend {
+    id: string;
+    label: string;
+    capabilities: FsCapabilities;
+    initialPath(): string;
+    list(path: string, opts?: ReadOptions): Promise<DriveListing>;
+    readBlob(item: DriveItem, opts?: ReadOptions): Promise<ReadResult>;
+    upload(dirPath: string, files: File[]): Promise<void>;
+    mkdir(dirPath: string, name: string): Promise<void>;
+    rename(item: DriveItem, currentDir: string, newName: string): Promise<void>;
+    remove(item: DriveItem): Promise<void>;
+    canWriteDir(path: string): boolean;
+    canWriteItem(item: DriveItem): boolean;
+    notice(path: string): string | null;
+}

package/dist/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/components/file-item.d.ts

@@ -0,0 +1,16 @@
+import type { DriveItem } from "../types.js";
+export declare const PREVIEW_LIMIT_BYTES: number;
+export interface PreviewState {
+    status: "idle" | "loading" | "ready" | "unsupported" | "too_large" | "error";
+    kind: "" | "image" | "text";
+    text: string;
+    url: string;
+    message: string;
+}
+export declare const IDLE_PREVIEW: PreviewState;
+export declare function previewKind(item: DriveItem): "" | "image" | "text";
+export declare function sortItems(items: DriveItem[]): DriveItem[];
+export declare function FileIcon({ item, small, }: {
+    item: DriveItem;
+    small?: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/file-item.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@ziioapp/ui/lib/utils";
+import { extLabel, guessContentType } from "../format.js";
+export const PREVIEW_LIMIT_BYTES = 512 * 1024;
+export const IDLE_PREVIEW = {
+    status: "idle",
+    kind: "",
+    text: "",
+    url: "",
+    message: "",
+};
+export function previewKind(item) {
+    if (!item || item.isDirectory)
+        return "";
+    const type = item.contentType || guessContentType(item.name);
+    if (type.startsWith("image/"))
+        return "image";
+    if (type.startsWith("text/") ||
+        [
+            "application/json",
+            "application/json5",
+            "application/xml",
+            "application/yaml",
+            "application/x-yaml",
+            "image/svg+xml",
+        ].includes(type)) {
+        return "text";
+    }
+    return "";
+}
+export function sortItems(items) {
+    return [...items].sort((a, b) => {
+        if (a.isDirectory !== b.isDirectory)
+            return a.isDirectory ? -1 : 1;
+        return a.name.localeCompare(b.name, "zh-Hans-CN");
+    });
+}
+export function FileIcon({ item, small, }) {
+    return (_jsx("div", { className: cn("grid shrink-0 place-items-center rounded-md font-bold", small ? "size-6 text-[0.625rem]" : "size-9 text-xs", item.isDirectory
+            ? "bg-amber-100 text-amber-700 dark:bg-amber-500/20 dark:text-amber-300"
+            : "bg-muted text-muted-foreground"), children: item.isDirectory ? "DIR" : extLabel(item.name) }));
+}

package/dist/components/file-window.d.ts

@@ -0,0 +1,4 @@
+import type { FinderWindow } from "../store.js";
+export declare function FileWindow({ win }: {
+    win: FinderWindow;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/file-window.js

@@ -0,0 +1,100 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from "@ziioapp/ui/components/badge";
+import { Button } from "@ziioapp/ui/components/button";
+import { notify } from "@ziioapp/ui/lib/feedback";
+import { CloudDownload, Download } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useFinder } from "../context.js";
+import { formatBytes, guessContentType } from "../format.js";
+import { IDLE_PREVIEW, PREVIEW_LIMIT_BYTES, previewKind, } from "./file-item.js";
+export function FileWindow({ win }) {
+    const { backend } = useFinder();
+    if (!win.fileItem) {
+        throw new Error("FileWindow requires a file item.");
+    }
+    const item = win.fileItem;
+    const cap = backend.capabilities;
+    const [preview, setPreview] = useState(IDLE_PREVIEW);
+    const [busy, setBusy] = useState(false);
+    const [forceLoad, setForceLoad] = useState(false);
+    const [fromCache, setFromCache] = useState(false);
+    const urlRef = useRef("");
+    const loadPreview = useCallback(async (forceFresh) => {
+        if (urlRef.current) {
+            URL.revokeObjectURL(urlRef.current);
+            urlRef.current = "";
+        }
+        const kind = previewKind(item);
+        if (!kind) {
+            setPreview({
+                ...IDLE_PREVIEW,
+                status: "unsupported",
+                message: "此类型暂不支持内联预览。",
+            });
+            return;
+        }
+        if (!(forceLoad || forceFresh) &&
+            Number(item.size) > PREVIEW_LIMIT_BYTES) {
+            setPreview({
+                ...IDLE_PREVIEW,
+                status: "too_large",
+                message: `文件超过 ${formatBytes(PREVIEW_LIMIT_BYTES)}，未自动预览。`,
+            });
+            return;
+        }
+        setPreview({ ...IDLE_PREVIEW, status: "loading", kind });
+        try {
+            const { blob, fromCache: cached } = await backend.readBlob(item, {
+                forceFresh,
+            });
+            setFromCache(cached);
+            const type = item.contentType || guessContentType(item.name);
+            if (kind === "image" && type !== "image/svg+xml") {
+                const url = URL.createObjectURL(blob);
+                urlRef.current = url;
+                setPreview({ ...IDLE_PREVIEW, status: "ready", kind: "image", url });
+            }
+            else {
+                const text = await blob.text();
+                setPreview({ ...IDLE_PREVIEW, status: "ready", kind: "text", text });
+            }
+        }
+        catch (cause) {
+            setPreview({
+                ...IDLE_PREVIEW,
+                status: "error",
+                message: `预览失败：${cause.message}`,
+            });
+        }
+    }, [backend, item, forceLoad]);
+    useEffect(() => {
+        void loadPreview(false);
+        return () => {
+            if (urlRef.current)
+                URL.revokeObjectURL(urlRef.current);
+        };
+    }, [loadPreview]);
+    async function downloadItem() {
+        setBusy(true);
+        try {
+            const { blob } = await backend.readBlob(item);
+            const url = URL.createObjectURL(blob);
+            const link = document.createElement("a");
+            link.href = url;
+            link.download = item.name;
+            document.body.appendChild(link);
+            link.click();
+            link.remove();
+            URL.revokeObjectURL(url);
+            notify.success("下载已开始。");
+        }
+        catch (cause) {
+            notify.fromError(cause, "下载失败");
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    const showCacheBadge = cap.cache && preview.status === "ready";
+    return (_jsxs("div", { className: "flex h-full flex-col", children: [_jsxs("div", { className: "flex min-h-0 flex-1 items-center justify-center overflow-auto bg-muted/20 p-3", children: [preview.status === "loading" && (_jsx("div", { className: "text-xs text-muted-foreground", children: "\u6B63\u5728\u52A0\u8F7D\u9884\u89C8..." })), preview.kind === "image" && preview.url && (_jsx("img", { src: preview.url, alt: item.name, className: "max-h-full max-w-full rounded-md object-contain" })), preview.kind === "text" && preview.status === "ready" && (_jsx("pre", { className: "size-full overflow-auto rounded-md border border-border bg-card p-3 font-mono text-xs break-all whitespace-pre-wrap", children: preview.text })), (preview.status === "unsupported" || preview.status === "error") && (_jsx("div", { className: "text-center text-xs text-muted-foreground", children: preview.message })), preview.status === "too_large" && (_jsxs("div", { className: "flex flex-col items-center gap-2 text-center text-xs text-muted-foreground", children: [_jsx("span", { children: preview.message }), _jsx(Button, { variant: "outline", size: "sm", onClick: () => setForceLoad(true), children: "\u4ECD\u8981\u52A0\u8F7D" })] }))] }), _jsxs("div", { className: "flex shrink-0 items-center justify-between gap-2 border-t px-3 py-2", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-1.5 text-[0.625rem] text-muted-foreground", children: [showCacheBadge && (_jsx(Badge, { variant: fromCache ? "secondary" : "outline", children: fromCache ? "缓存" : "实时" })), _jsxs("div", { className: "min-w-0", children: [_jsxs("div", { className: "truncate", children: [formatBytes(item.size), " \u00B7", " ", item.contentType || guessContentType(item.name) || "文件"] }), _jsxs("div", { className: "truncate font-mono", children: ["/", item.path] })] })] }), _jsxs("div", { className: "flex shrink-0 items-center gap-1.5", children: [cap.cache && fromCache && preview.status === "ready" && (_jsxs(Button, { variant: "outline", size: "sm", disabled: busy, onClick: () => void loadPreview(true), children: [_jsx(CloudDownload, {}), "\u8BFB\u53D6\u771F\u6587\u4EF6"] })), _jsxs(Button, { variant: "outline", size: "sm", disabled: busy, onClick: () => void downloadItem(), children: [_jsx(Download, {}), "\u4E0B\u8F7D"] })] })] })] }));
+}

package/dist/components/folder-window.d.ts

@@ -0,0 +1,4 @@
+import type { FinderWindow } from "../store.js";
+export declare function FolderWindow({ win }: {
+    win: FinderWindow;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/folder-window.js

@@ -0,0 +1,242 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, AlertAction, AlertDescription, AlertTitle, } from "@ziioapp/ui/components/alert";
+import { Badge } from "@ziioapp/ui/components/badge";
+import { Button } from "@ziioapp/ui/components/button";
+import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger, } from "@ziioapp/ui/components/context-menu";
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyTitle, } from "@ziioapp/ui/components/empty";
+import { Input } from "@ziioapp/ui/components/input";
+import { Skeleton } from "@ziioapp/ui/components/skeleton";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from "@ziioapp/ui/components/table";
+import { notify } from "@ziioapp/ui/lib/feedback";
+import { cn } from "@ziioapp/ui/lib/utils";
+import { ArrowUp, ChevronLeft, CloudDownload, FolderPlus, Home, LayoutGrid, List, RefreshCw, Upload, } from "lucide-react";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { useSnapshot } from "valtio";
+import { asyncStateData, settleAsyncState } from "../async-state.js";
+import { useFinder } from "../context.js";
+import { formatBytes, guessContentType } from "../format.js";
+import { FileIcon, sortItems } from "./file-item.js";
+function parentOf(path) {
+    const parts = path.split("/").filter(Boolean);
+    parts.pop();
+    return parts.join("/");
+}
+export function FolderWindow({ win }) {
+    const { api, backend } = useFinder();
+    const snap = useSnapshot(api.store);
+    const path = win.path ?? "";
+    const viewMode = win.viewMode ?? "list";
+    const refreshTick = snap.refreshSignal[path] ?? 0;
+    const [listingState, setListingState] = useState({
+        status: "idle",
+    });
+    const [selectedPath, setSelectedPath] = useState("");
+    const [operationPending, setOperationPending] = useState(false);
+    const [dragActive, setDragActive] = useState(false);
+    const [pendingDialog, setPendingDialog] = useState(null);
+    const dialogNameId = useId();
+    const fileInputRef = useRef(null);
+    const cap = backend.capabilities;
+    const inWritableArea = backend.canWriteDir(path);
+    const notice = backend.notice(path);
+    const listing = asyncStateData(listingState);
+    const items = listing?.items ?? [];
+    const fromCache = listing?.fromCache ?? false;
+    const loading = listingState.status === "loading";
+    const busy = loading || operationPending;
+    const load = useCallback(async (forceFresh) => {
+        setListingState((current) => ({
+            status: "loading",
+            previous: forceFresh ? asyncStateData(current) : undefined,
+        }));
+        try {
+            const nextListing = await backend.list(path, { forceFresh });
+            setListingState(settleAsyncState(nextListing, (result) => result.items.length === 0));
+            setSelectedPath("");
+        }
+        catch (cause) {
+            const error = cause instanceof Error ? cause : new Error("目录加载失败");
+            setListingState((current) => ({
+                status: "error",
+                error,
+                previous: asyncStateData(current),
+            }));
+            notify.fromError(cause, "目录加载失败");
+        }
+    }, [backend, path]);
+    // 路径变化或收到刷新信号时重载
+    useEffect(() => {
+        void refreshTick;
+        void load(false);
+    }, [load, refreshTick]);
+    const openItem = (item) => {
+        if (item.isDirectory)
+            api.navigateWindow(win.id, item.path);
+        else
+            api.openFile(item);
+    };
+    const uploadFiles = async (fileList) => {
+        if (!inWritableArea) {
+            notify.warning("当前位置默认不可写入。");
+            return;
+        }
+        const files = [...fileList];
+        if (files.length === 0)
+            return;
+        setOperationPending(true);
+        try {
+            await backend.upload(path, files);
+            notify.success(`已上传 ${files.length} 个文件。`);
+            api.bumpRefresh(path);
+        }
+        catch (cause) {
+            notify.fromError(cause, "上传失败");
+        }
+        finally {
+            setOperationPending(false);
+        }
+    };
+    const createFolder = () => {
+        if (!inWritableArea) {
+            notify.warning("当前位置默认不可写入。");
+            return;
+        }
+        setPendingDialog({ kind: "create-folder", value: "" });
+    };
+    const submitCreateFolder = async (name) => {
+        if (!name)
+            return;
+        setOperationPending(true);
+        try {
+            await backend.mkdir(path, name);
+            notify.success("文件夹已创建。");
+            api.bumpRefresh(path);
+            setPendingDialog(null);
+        }
+        catch (cause) {
+            notify.fromError(cause, "创建失败");
+        }
+        finally {
+            setOperationPending(false);
+        }
+    };
+    const renameItem = (item) => {
+        if (!backend.canWriteItem(item)) {
+            notify.warning("当前位置默认不可重命名。");
+            return;
+        }
+        setPendingDialog({ kind: "rename", item, value: item.name });
+    };
+    const submitRenameItem = async (item, name) => {
+        if (!name || name === item.name)
+            return;
+        setOperationPending(true);
+        try {
+            await backend.rename(item, path, name);
+            notify.success("已重命名。");
+            api.bumpRefresh(path);
+            setPendingDialog(null);
+        }
+        catch (cause) {
+            notify.fromError(cause, "重命名失败");
+        }
+        finally {
+            setOperationPending(false);
+        }
+    };
+    const deleteItem = (item) => {
+        if (!backend.canWriteItem(item)) {
+            notify.warning("当前位置默认不可删除。");
+            return;
+        }
+        setPendingDialog({ kind: "delete", item });
+    };
+    const confirmDeleteItem = async (item) => {
+        setOperationPending(true);
+        try {
+            await backend.remove(item);
+            notify.success("已删除。");
+            api.bumpRefresh(path);
+            setPendingDialog(null);
+        }
+        catch (cause) {
+            notify.fromError(cause, "删除失败");
+        }
+        finally {
+            setOperationPending(false);
+        }
+    };
+    async function downloadItem(item) {
+        setOperationPending(true);
+        try {
+            const { blob } = await backend.readBlob(item);
+            const url = URL.createObjectURL(blob);
+            const link = document.createElement("a");
+            link.href = url;
+            link.download = item.name;
+            document.body.appendChild(link);
+            link.click();
+            link.remove();
+            URL.revokeObjectURL(url);
+            notify.success("下载已开始。");
+        }
+        catch (cause) {
+            notify.fromError(cause, "下载失败");
+        }
+        finally {
+            setOperationPending(false);
+        }
+    }
+    const sorted = sortItems(items);
+    const breadcrumbs = path.split("/").filter(Boolean);
+    const selectedItem = items.find((i) => i.path === selectedPath) || null;
+    // PLACEHOLDER_JSX
+    return (_jsxs("div", { className: "relative flex h-full flex-col", children: [_jsxs("div", { className: "flex shrink-0 flex-wrap items-center gap-1 border-b px-2 py-1.5", children: [_jsx(Button, { variant: "ghost", size: "icon-sm", disabled: busy || path === "", onClick: () => api.navigateWindow(win.id, parentOf(path)), "aria-label": "\u4E0A\u7EA7", children: _jsx(ArrowUp, {}) }), _jsx(Button, { variant: "ghost", size: "icon-sm", disabled: busy, onClick: () => api.navigateWindow(win.id, backend.initialPath()), "aria-label": "\u8D77\u59CB\u76EE\u5F55", children: _jsx(Home, {}) }), _jsx(Button, { variant: "ghost", size: "icon-sm", disabled: busy, onClick: () => void load(false), "aria-label": "\u5237\u65B0", children: _jsx(RefreshCw, { className: cn(busy && "animate-spin") }) }), cap.upload && (_jsxs(_Fragment, { children: [_jsx("div", { className: "mx-1 h-4 w-px bg-border" }), _jsx(Button, { variant: "ghost", size: "icon-sm", disabled: busy || !inWritableArea, onClick: () => fileInputRef.current?.click(), "aria-label": "\u4E0A\u4F20", children: _jsx(Upload, {}) }), _jsx(Button, { variant: "ghost", size: "icon-sm", disabled: busy || !inWritableArea, onClick: createFolder, "aria-label": "\u65B0\u5EFA\u6587\u4EF6\u5939", children: _jsx(FolderPlus, {}) })] })), _jsx("div", { className: "flex-1" }), cap.cache && fromCache && (_jsxs(Button, { variant: "outline", size: "xs", disabled: busy, onClick: () => void load(true), children: [_jsx(CloudDownload, {}), "\u8BFB\u53D6\u771F\u76EE\u5F55"] })), _jsxs("div", { className: "flex overflow-hidden rounded-md border border-border", children: [_jsx(Button, { variant: viewMode === "list" ? "secondary" : "ghost", size: "icon-sm", className: "rounded-none border-0", onClick: () => api.setWindowViewMode(win.id, "list"), "aria-label": "\u5217\u8868\u89C6\u56FE", children: _jsx(List, {}) }), _jsx(Button, { variant: viewMode === "grid" ? "secondary" : "ghost", size: "icon-sm", className: "rounded-none border-0", onClick: () => api.setWindowViewMode(win.id, "grid"), "aria-label": "\u7F51\u683C\u89C6\u56FE", children: _jsx(LayoutGrid, {}) })] })] }), _jsxs("div", { className: "flex shrink-0 flex-wrap items-center gap-0.5 border-b px-2 py-1 text-xs", children: [_jsx(Button, { variant: path === "" ? "secondary" : "ghost", size: "xs", onClick: () => api.navigateWindow(win.id, ""), children: "\u6839\u76EE\u5F55" }), breadcrumbs.map((name, index) => {
+                        const crumbPath = breadcrumbs.slice(0, index + 1).join("/");
+                        return (_jsxs("span", { className: "flex items-center gap-0.5", children: [_jsx(ChevronLeft, { className: "size-3 rotate-180 text-muted-foreground" }), _jsx(Button, { variant: "ghost", size: "xs", className: "max-w-36 truncate", onClick: () => api.navigateWindow(win.id, crumbPath), children: name })] }, crumbPath));
+                    })] }), notice && (_jsx("div", { className: "shrink-0 border-b bg-muted/30 px-2 py-1 text-[0.625rem] text-muted-foreground", children: notice })), _jsx("section", { className: cn("min-h-0 flex-1 overflow-auto p-2 transition-colors", dragActive && "bg-primary/5 ring-2 ring-inset ring-primary/40"), "aria-label": "\u6587\u4EF6\u5939\u5185\u5BB9", onDragEnter: (e) => {
+                    e.preventDefault();
+                    if (cap.upload)
+                        setDragActive(true);
+                }, onDragOver: (e) => {
+                    e.preventDefault();
+                    if (cap.upload)
+                        setDragActive(true);
+                }, onDragLeave: (e) => {
+                    e.preventDefault();
+                    setDragActive(false);
+                }, onDrop: (e) => {
+                    e.preventDefault();
+                    setDragActive(false);
+                    if (cap.upload)
+                        void uploadFiles(e.dataTransfer.files || []);
+                }, children: loading && items.length === 0 ? (_jsxs("div", { className: "flex flex-col gap-2 p-4", role: "status", "aria-label": "\u6B63\u5728\u52A0\u8F7D\u76EE\u5F55", children: [_jsx(Skeleton, { className: "h-7 w-full" }), _jsx(Skeleton, { className: "h-7 w-full" }), _jsx(Skeleton, { className: "h-7 w-3/4" })] })) : listingState.status === "error" && items.length === 0 ? (_jsxs(Alert, { variant: "destructive", children: [_jsx(AlertTitle, { children: "\u65E0\u6CD5\u52A0\u8F7D\u76EE\u5F55" }), _jsx(AlertDescription, { children: listingState.error.message }), _jsx(AlertAction, { children: _jsx(Button, { variant: "outline", size: "sm", onClick: () => void load(false), children: "\u91CD\u8BD5" }) })] })) : listingState.status === "empty" ? (_jsxs(Empty, { children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: "\u5F53\u524D\u6587\u4EF6\u5939\u4E3A\u7A7A" }), _jsx(EmptyDescription, { children: cap.upload && inWritableArea
+                                        ? "可以拖入文件或点击上传。"
+                                        : "这里暂时没有内容。" })] }), cap.upload && inWritableArea ? (_jsx(EmptyContent, { children: _jsxs(Button, { variant: "outline", size: "sm", onClick: () => fileInputRef.current?.click(), children: [_jsx(Upload, { "data-icon": "inline-start" }), "\u4E0A\u4F20\u6587\u4EF6"] }) })) : null] })) : viewMode === "list" ? (_jsxs(Table, { children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { children: "\u540D\u79F0" }), _jsx(TableHead, { className: "text-end", children: "\u5927\u5C0F" }), _jsx(TableHead, { children: "\u4FEE\u6539\u65F6\u95F4" })] }) }), _jsx(TableBody, { children: sorted.map((item) => (_jsxs(ItemContextMenu, { item: item, canWrite: backend.canWriteItem(item), capUpload: cap.upload, onOpen: () => openItem(item), onOpenNewWindow: () => item.isDirectory
+                                    ? api.openFolder(item.path, { inNewWindow: true })
+                                    : api.openFile(item), onDownload: () => void downloadItem(item), onRename: () => renameItem(item), onDelete: () => deleteItem(item), render: _jsx("tr", { className: cn("cursor-pointer border-b transition-colors hover:bg-muted/50", selectedPath === item.path && "bg-muted"), onClick: () => setSelectedPath(item.path), onDoubleClick: () => openItem(item) }), children: [_jsx(TableCell, { className: "max-w-0", children: _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(FileIcon, { item: item, small: true }), _jsx("span", { className: "truncate", title: item.name, children: item.name })] }) }), _jsx(TableCell, { className: "text-end text-muted-foreground", children: item.isDirectory ? "-" : formatBytes(item.size) }), _jsx(TableCell, { className: "text-muted-foreground", children: item.modified || "-" })] }, item.path))) })] })) : (_jsx("div", { className: "grid grid-cols-[repeat(auto-fill,minmax(110px,1fr))] gap-2", children: sorted.map((item) => (_jsxs(ItemContextMenu, { item: item, canWrite: backend.canWriteItem(item), capUpload: cap.upload, onOpen: () => openItem(item), onOpenNewWindow: () => item.isDirectory
+                            ? api.openFolder(item.path, { inNewWindow: true })
+                            : api.openFile(item), onDownload: () => void downloadItem(item), onRename: () => renameItem(item), onDelete: () => deleteItem(item), render: _jsx("button", { type: "button", onClick: () => setSelectedPath(item.path), onDoubleClick: () => openItem(item), className: cn("flex min-h-28 w-full min-w-0 flex-col items-center gap-2 overflow-hidden rounded-lg border border-transparent p-2 text-center transition-colors hover:bg-muted/50", selectedPath === item.path &&
+                                "border-primary/40 bg-primary/5") }), children: [_jsx(FileIcon, { item: item }), _jsx("div", { className: "line-clamp-2 w-full text-xs break-all", title: item.name, children: item.name })] }, item.path))) })) }), _jsxs("div", { className: "flex shrink-0 items-center justify-between gap-2 border-t px-2 py-1 text-[0.625rem] text-muted-foreground", children: [_jsxs("span", { className: "flex items-center gap-1.5", children: [items.length, " \u9879", cap.cache && (_jsx(Badge, { variant: fromCache ? "secondary" : "outline", children: fromCache ? "缓存" : "实时" }))] }), selectedItem && (_jsxs("span", { className: "min-w-0 truncate", children: [selectedItem.name, !selectedItem.isDirectory &&
+                                ` · ${formatBytes(selectedItem.size)}`, !selectedItem.isDirectory &&
+                                ` · ${selectedItem.contentType || guessContentType(selectedItem.name) || "文件"}`] }))] }), _jsx("input", { ref: fileInputRef, className: "hidden", type: "file", multiple: true, onChange: (e) => {
+                    void uploadFiles(e.target.files || []);
+                    e.target.value = "";
+                } }), pendingDialog && (_jsx("div", { className: "absolute inset-0 z-20 flex items-center justify-center bg-background/55 p-4 backdrop-blur-sm", children: _jsx("div", { className: "w-full max-w-xs rounded-lg border bg-card p-4 text-sm shadow-xl", children: pendingDialog.kind === "delete" ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "font-medium", children: "\u5220\u9664\u9879\u76EE" }), _jsxs("div", { className: "mt-2 text-muted-foreground", children: ["\u786E\u5B9A\u5220\u9664\u300C", pendingDialog.item.name, "\u300D\uFF1F"] }), _jsxs("div", { className: "mt-4 flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: busy, onClick: () => setPendingDialog(null), children: "\u53D6\u6D88" }), _jsx(Button, { type: "button", variant: "destructive", size: "sm", disabled: busy, onClick: () => void confirmDeleteItem(pendingDialog.item), children: "\u5220\u9664" })] })] })) : (_jsxs("form", { onSubmit: (event) => {
+                            event.preventDefault();
+                            const name = pendingDialog.value.trim();
+                            if (pendingDialog.kind === "create-folder") {
+                                void submitCreateFolder(name);
+                                return;
+                            }
+                            void submitRenameItem(pendingDialog.item, name);
+                        }, children: [_jsx("label", { className: "block font-medium", htmlFor: dialogNameId, children: pendingDialog.kind === "create-folder"
+                                    ? "文件夹名称"
+                                    : "新名称" }), _jsx(Input, { id: dialogNameId, className: "mt-2", autoFocus: true, value: pendingDialog.value, onChange: (event) => setPendingDialog({
+                                    ...pendingDialog,
+                                    value: event.target.value,
+                                }) }), _jsxs("div", { className: "mt-4 flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: busy, onClick: () => setPendingDialog(null), children: "\u53D6\u6D88" }), _jsx(Button, { type: "submit", size: "sm", disabled: busy, children: "\u786E\u5B9A" })] })] })) }) }))] }));
+}
+function ItemContextMenu({ item, canWrite, capUpload, onOpen, onOpenNewWindow, onDownload, onRename, onDelete, render, children, }) {
+    return (_jsxs(ContextMenu, { children: [_jsx(ContextMenuTrigger, { render: render, children: children }), _jsxs(ContextMenuContent, { children: [_jsx(ContextMenuItem, { onClick: onOpen, children: "\u6253\u5F00" }), _jsx(ContextMenuItem, { onClick: onOpenNewWindow, children: "\u5728\u65B0\u7A97\u53E3\u6253\u5F00" }), !item.isDirectory && (_jsx(ContextMenuItem, { onClick: onDownload, children: "\u4E0B\u8F7D" })), capUpload && (_jsxs(_Fragment, { children: [_jsx(ContextMenuSeparator, {}), _jsx(ContextMenuItem, { disabled: !canWrite, onClick: onRename, children: "\u91CD\u547D\u540D" }), _jsx(ContextMenuItem, { variant: "destructive", disabled: !canWrite, onClick: onDelete, children: "\u5220\u9664" })] }))] })] }));
+}

package/dist/components/window-frame.d.ts

@@ -0,0 +1,31 @@
+import type { Rect } from "../store.js";
+export interface WindowFrameModel {
+    id: string;
+    title: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    state: "normal" | "maximized" | "minimized";
+    z: number;
+}
+interface WindowFrameProps {
+    win: WindowFrameModel;
+    focused: boolean;
+    className?: string;
+    titlebarClassName?: string;
+    contentClassName?: string;
+    minWidth?: number;
+    minHeight?: number;
+    /** 返回桌面当前像素尺寸，用于约束与最大化。 */
+    getDesktopRect: () => Rect;
+    onFocus: (id: string) => void;
+    onMove: (id: string, x: number, y: number) => void;
+    onResize: (id: string, rect: Rect) => void;
+    onClose?: (id: string) => void;
+    onMinimize?: (id: string) => void;
+    onToggleMaximize?: (id: string, desktop: Rect) => void;
+    children: React.ReactNode;
+}
+export declare function WindowFrame({ win, focused, className, titlebarClassName, contentClassName, minWidth, minHeight, getDesktopRect, onFocus, onMove, onResize, onClose, onMinimize, onToggleMaximize, children, }: WindowFrameProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/window-frame.js

@@ -0,0 +1,150 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@ziioapp/ui/lib/utils";
+import { useRef } from "react";
+const MIN_W = 320;
+const MIN_H = 220;
+const TITLEBAR_H = 36;
+export function WindowFrame({ win, focused, className, titlebarClassName, contentClassName, minWidth = MIN_W, minHeight = MIN_H, getDesktopRect, onFocus, onMove, onResize, onClose, onMinimize, onToggleMaximize, children, }) {
+    const dragState = useRef(null);
+    const resizeState = useRef(null);
+    const rafRef = useRef(null);
+    const pendingRef = useRef(null);
+    const maximized = win.state === "maximized";
+    const flush = () => {
+        rafRef.current = null;
+        const next = pendingRef.current;
+        if (!next)
+            return;
+        pendingRef.current = null;
+        if (resizeState.current) {
+            onResize(win.id, next);
+        }
+        else {
+            onMove(win.id, next.x, next.y);
+        }
+    };
+    const schedule = (rect) => {
+        pendingRef.current = rect;
+        if (rafRef.current == null) {
+            rafRef.current = requestAnimationFrame(flush);
+        }
+    };
+    // ----- 拖拽移动 -----
+    const onTitlePointerDown = (e) => {
+        if (e.button !== 0)
+            return;
+        onFocus(win.id);
+        if (maximized)
+            return; // 最大化时不拖动
+        e.target.setPointerCapture(e.pointerId);
+        dragState.current = {
+            startX: e.clientX,
+            startY: e.clientY,
+            origX: win.x,
+            origY: win.y,
+        };
+    };
+    const onTitlePointerMove = (e) => {
+        const drag = dragState.current;
+        if (!drag)
+            return;
+        const desktop = getDesktopRect();
+        const dx = e.clientX - drag.startX;
+        const dy = e.clientY - drag.startY;
+        // 软约束：标题栏始终可抓取
+        const minX = -win.width + 80;
+        const maxX = desktop.width - 80;
+        const minY = 0;
+        const maxY = desktop.height - TITLEBAR_H;
+        const x = Math.max(minX, Math.min(drag.origX + dx, maxX));
+        const y = Math.max(minY, Math.min(drag.origY + dy, maxY));
+        schedule({ x, y, width: win.width, height: win.height });
+    };
+    const endDrag = (e) => {
+        if (dragState.current) {
+            e.target.releasePointerCapture?.(e.pointerId);
+            dragState.current = null;
+        }
+    };
+    // ----- 八方向缩放 -----
+    const onResizePointerDown = (dir) => (e) => {
+        if (e.button !== 0)
+            return;
+        e.stopPropagation();
+        onFocus(win.id);
+        e.target.setPointerCapture(e.pointerId);
+        resizeState.current = {
+            dir,
+            startX: e.clientX,
+            startY: e.clientY,
+            orig: { x: win.x, y: win.y, width: win.width, height: win.height },
+        };
+    };
+    const onResizePointerMove = (e) => {
+        const rs = resizeState.current;
+        if (!rs)
+            return;
+        const desktop = getDesktopRect();
+        const dx = e.clientX - rs.startX;
+        const dy = e.clientY - rs.startY;
+        let { x, y, width, height } = rs.orig;
+        if (rs.dir.includes("e")) {
+            width = Math.min(Math.max(minWidth, rs.orig.width + dx), desktop.width - rs.orig.x);
+        }
+        if (rs.dir.includes("s")) {
+            height = Math.min(Math.max(minHeight, rs.orig.height + dy), desktop.height - rs.orig.y);
+        }
+        if (rs.dir.includes("w")) {
+            const right = rs.orig.x + rs.orig.width;
+            const newX = Math.min(Math.max(0, rs.orig.x + dx), right - minWidth);
+            width = right - newX;
+            x = newX;
+        }
+        if (rs.dir.includes("n")) {
+            const bottom = rs.orig.y + rs.orig.height;
+            const newY = Math.min(Math.max(0, rs.orig.y + dy), bottom - minHeight);
+            height = bottom - newY;
+            y = newY;
+        }
+        schedule({ x, y, width, height });
+    };
+    const endResize = (e) => {
+        if (resizeState.current) {
+            e.target.releasePointerCapture?.(e.pointerId);
+            resizeState.current = null;
+        }
+    };
+    const handles = [
+        { dir: "n", className: "top-0 inset-x-2 h-1.5 cursor-ns-resize" },
+        { dir: "s", className: "bottom-0 inset-x-2 h-1.5 cursor-ns-resize" },
+        { dir: "e", className: "right-0 inset-y-2 w-1.5 cursor-ew-resize" },
+        { dir: "w", className: "left-0 inset-y-2 w-1.5 cursor-ew-resize" },
+        { dir: "ne", className: "top-0 right-0 size-2.5 cursor-nesw-resize" },
+        { dir: "nw", className: "top-0 left-0 size-2.5 cursor-nwse-resize" },
+        { dir: "se", className: "bottom-0 right-0 size-2.5 cursor-nwse-resize" },
+        { dir: "sw", className: "bottom-0 left-0 size-2.5 cursor-nesw-resize" },
+    ];
+    return (_jsxs("div", { className: cn("absolute isolate flex flex-col rounded-xl border bg-card shadow-lg transition-shadow", focused
+            ? "border-border shadow-2xl ring-1 ring-foreground/10"
+            : "border-border/60", 
+        // "bg-blue-500 border-green-500 ring-red-500",
+        "overflow-hidden", className), style: {
+            left: win.x,
+            top: win.y,
+            width: win.width,
+            height: win.height,
+            zIndex: win.z,
+        }, onPointerDown: () => onFocus(win.id), children: [_jsxs("div", { role: "toolbar", "aria-label": `${win.title} 窗口标题栏`, className: cn("flex shrink-0 items-center gap-2 rounded-t-[inherit] border-b bg-card px-3 select-none", maximized ? "cursor-default" : "cursor-grab active:cursor-grabbing", titlebarClassName), style: { height: TITLEBAR_H }, onPointerDown: onTitlePointerDown, onPointerMove: onTitlePointerMove, onPointerUp: endDrag, onPointerCancel: endDrag, onDoubleClick: () => onToggleMaximize?.(win.id, getDesktopRect()), children: [_jsxs("fieldset", { "aria-label": "\u7A97\u53E3\u63A7\u5236", className: "group/lights flex w-13 items-center gap-2 border-0 p-0", onPointerDown: (e) => e.stopPropagation(), onDoubleClick: (e) => e.stopPropagation(), children: [onClose && (_jsx(TrafficLight, { color: "close", onClick: () => onClose(win.id) })), onMinimize && (_jsx(TrafficLight, { color: "min", onClick: () => onMinimize(win.id) })), onToggleMaximize && (_jsx(TrafficLight, { color: "max", onClick: () => onToggleMaximize(win.id, getDesktopRect()) }))] }), _jsx("div", { className: "min-w-0 flex-1 truncate text-center text-xs font-medium text-foreground/80", children: win.title }), _jsx("div", { className: "w-13 shrink-0" })] }), _jsx("div", { className: cn("min-h-0 flex-1 overflow-hidden bg-background", contentClassName), children: children }), !maximized &&
+                handles.map((h) => (_jsx("div", { className: cn("absolute z-10", h.className), onPointerDown: onResizePointerDown(h.dir), onPointerMove: onResizePointerMove, onPointerUp: endResize, onPointerCancel: endResize }, h.dir)))] }));
+}
+function TrafficLight({ color, onClick, }) {
+    const styles = {
+        close: "bg-[#ff5f57] hover:bg-[#ff5f57]/80",
+        min: "bg-[#febc2e] hover:bg-[#febc2e]/80",
+        max: "bg-[#28c840] hover:bg-[#28c840]/80",
+    }[color];
+    return (_jsx("button", { type: "button", "aria-label": color, className: cn("size-3 rounded-full transition-colors", styles), onClick: (e) => {
+            e.stopPropagation();
+            onClick();
+        } }));
+}

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+import type { FsBackend } from "./backend.js";
+import type { FinderStoreApi } from "./store.js";
+export interface FinderContextValue {
+    api: FinderStoreApi;
+    backend: FsBackend;
+}
+export declare function FinderProvider({ value, children, }: {
+    value: FinderContextValue;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useFinder(): FinderContextValue;

package/dist/context.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const FinderContext = createContext(null);
+export function FinderProvider({ value, children, }) {
+    return (_jsx(FinderContext.Provider, { value: value, children: children }));
+}
+export function useFinder() {
+    const ctx = useContext(FinderContext);
+    if (!ctx)
+        throw new Error("useFinder must be used within FinderProvider");
+    return ctx;
+}

package/dist/finder-desktop.d.ts

@@ -0,0 +1,6 @@
+import type { FsBackend } from "./backend.js";
+import type { FinderStoreApi } from "./store.js";
+export declare function FinderDesktop({ backend, api, }: {
+    backend: FsBackend;
+    api: FinderStoreApi;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/finder-desktop.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "@ziioapp/ui/components/button";
+import { cn } from "@ziioapp/ui/lib/utils";
+import { FolderPlus } from "lucide-react";
+import { useCallback, useEffect, useRef } from "react";
+import { useSnapshot } from "valtio";
+import { FileIcon } from "./components/file-item.js";
+import { FileWindow } from "./components/file-window.js";
+import { FolderWindow } from "./components/folder-window.js";
+import { WindowFrame } from "./components/window-frame.js";
+import { FinderProvider } from "./context.js";
+export function FinderDesktop({ backend, api, }) {
+    const snap = useSnapshot(api.store);
+    const desktopRef = useRef(null);
+    const didInit = useRef(false);
+    const getDesktopRect = useCallback(() => {
+        const el = desktopRef.current;
+        if (!el)
+            return { x: 0, y: 0, width: 1024, height: 720 };
+        return { x: 0, y: 0, width: el.clientWidth, height: el.clientHeight };
+    }, []);
+    // 首次进入：恢复视图偏好并打开初始窗口。
+    useEffect(() => {
+        api.restoreViewMode();
+        if (!didInit.current) {
+            didInit.current = true;
+            api.openFolder(backend.initialPath(), { desktop: getDesktopRect() });
+        }
+    }, [
+        getDesktopRect,
+        api.restoreViewMode,
+        backend.initialPath,
+        api.openFolder,
+    ]);
+    const handleNewWindow = () => {
+        api.openFolder(backend.initialPath(), {
+            inNewWindow: true,
+            desktop: getDesktopRect(),
+        });
+    };
+    const minimized = snap.windows.filter((w) => w.state === "minimized");
+    return (_jsx(FinderProvider, { value: { backend, api }, children: _jsxs("div", { className: "flex h-full flex-col overflow-hidden rounded-md bg-background", children: [_jsxs("div", { className: "flex shrink-0 items-center gap-2 border-b bg-card/40 px-3 py-1.5 backdrop-blur-sm", children: [_jsx("span", { className: "text-sm font-medium", children: backend.label }), _jsx("div", { className: "flex-1" }), _jsxs(Button, { variant: "outline", size: "sm", onClick: handleNewWindow, children: [_jsx(FolderPlus, {}), "\u65B0\u5EFA\u7A97\u53E3"] })] }), _jsxs("div", { ref: desktopRef, className: "relative min-h-0 flex-1 overflow-hidden bg-[radial-gradient(var(--muted)_1px,transparent_1px)] [background-size:22px_22px]", children: [snap.windows.length === 0 ? (_jsxs("div", { className: "flex h-full flex-col items-center justify-center gap-3 text-muted-foreground", children: [_jsx("div", { className: "text-sm", children: "\u6CA1\u6709\u6253\u5F00\u7684\u7A97\u53E3" }), _jsxs(Button, { variant: "outline", size: "sm", onClick: handleNewWindow, children: [_jsx(FolderPlus, {}), "\u6253\u5F00"] })] })) : (snap.windows.map((win) => win.state === "minimized" ? null : (_jsx(WindowFrame, { win: win, focused: snap.focusedId === win.id, getDesktopRect: getDesktopRect, onFocus: api.focusWindow, onMove: api.moveWindow, onResize: api.resizeWindow, onClose: api.closeWindow, onMinimize: api.minimizeWindow, onToggleMaximize: api.toggleMaximize, children: win.kind === "folder" ? (_jsx(FolderWindow, { win: win })) : (_jsx(FileWindow, { win: win })) }, win.id)))), minimized.length > 0 && (_jsx("div", { className: "absolute inset-x-0 bottom-0 flex items-center justify-center gap-2 p-2", children: _jsx("div", { className: "flex max-w-full items-center gap-1.5 overflow-x-auto rounded-xl border bg-card/80 p-1.5 shadow-lg backdrop-blur-md", children: minimized.map((win) => (_jsxs("button", { type: "button", onClick: () => api.restoreWindow(win.id), className: cn("flex items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors hover:bg-muted"), title: win.title, children: [_jsx(FileIcon, { item: {
+                                                name: win.kind === "folder" ? "" : win.title,
+                                                path: "",
+                                                size: 0,
+                                                contentType: "",
+                                                modified: "",
+                                                isDirectory: win.kind === "folder",
+                                            }, small: true }), _jsx("span", { className: "max-w-28 truncate", children: win.title })] }, win.id))) }) }))] })] }) }));
+}

package/dist/format.d.ts

@@ -0,0 +1,3 @@
+export declare function formatBytes(bytes: number | null | undefined): string;
+export declare function extLabel(name: string): string;
+export declare function guessContentType(name: string): string;

package/dist/format.js

@@ -0,0 +1,45 @@
+export function formatBytes(bytes) {
+    const value = Number(bytes ?? 0);
+    if (!Number.isFinite(value) || value <= 0)
+        return "0 B";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    const index = Math.min(units.length - 1, Math.floor(Math.log(value) / Math.log(1024)));
+    return `${(value / 1024 ** index).toFixed(index === 0 ? 0 : 1)} ${units[index]}`;
+}
+export function extLabel(name) {
+    const ext = String(name || "")
+        .split(".")
+        .pop();
+    return ext && ext !== name ? ext.slice(0, 4).toUpperCase() : "FILE";
+}
+export function guessContentType(name) {
+    const ext = String(name || "")
+        .split(".")
+        .pop()
+        ?.toLowerCase();
+    const map = {
+        txt: "text/plain",
+        md: "text/markdown",
+        markdown: "text/markdown",
+        json: "application/json",
+        json5: "application/json5",
+        xml: "application/xml",
+        yml: "application/yaml",
+        yaml: "application/yaml",
+        csv: "text/csv",
+        log: "text/plain",
+        html: "text/html",
+        htm: "text/html",
+        css: "text/css",
+        js: "text/javascript",
+        ts: "text/typescript",
+        svg: "image/svg+xml",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        avif: "image/avif",
+    };
+    return (ext && map[ext]) || "";
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { DriveListing, FsBackend, FsCapabilities, ReadOptions, ReadResult, } from "./backend.js";
+export { WindowFrame, type WindowFrameModel, } from "./components/window-frame.js";
+export { FinderDesktop } from "./finder-desktop.js";
+export { extLabel, formatBytes, guessContentType } from "./format.js";
+export { joinPath } from "./path.js";
+export type { FinderState, FinderStoreApi, FinderWindow, Rect, ViewMode, WinKind, WinState, } from "./store.js";
+export { createFinderStore, pathTitle } from "./store.js";
+export type { DriveItem } from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// biome-ignore-all lint/performance/noBarrelFile: Finder feature public entry.
+export { WindowFrame, } from "./components/window-frame.js";
+export { FinderDesktop } from "./finder-desktop.js";
+export { extLabel, formatBytes, guessContentType } from "./format.js";
+export { joinPath } from "./path.js";
+export { createFinderStore, pathTitle } from "./store.js";

package/dist/path.d.ts

@@ -0,0 +1 @@
+export declare function joinPath(parent: string, name: string): string;

package/dist/path.js

@@ -0,0 +1,4 @@
+export function joinPath(parent, name) {
+    const cleanName = String(name || "").replace(/^\/+|\/+$/g, "");
+    return [parent, cleanName].filter(Boolean).join("/");
+}

package/dist/store.d.ts

@@ -0,0 +1,57 @@
+import type { DriveItem } from "./types.js";
+export type WinKind = "folder" | "file";
+export type WinState = "normal" | "maximized" | "minimized";
+export type ViewMode = "list" | "grid";
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FinderWindow {
+    id: string;
+    kind: WinKind;
+    title: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    prevRect?: Rect;
+    state: WinState;
+    z: number;
+    path?: string;
+    viewMode?: ViewMode;
+    fileItem?: DriveItem;
+}
+export interface FinderState {
+    windows: FinderWindow[];
+    focusedId: string | null;
+    nextZ: number;
+    spawnIndex: number;
+    defaultViewMode: ViewMode;
+    refreshSignal: Record<string, number>;
+}
+declare function pathTitle(path: string): string;
+export interface FinderStoreApi {
+    store: FinderState;
+    viewModeKey: string;
+    openFolder: (path: string, options?: {
+        inNewWindow?: boolean;
+        desktop?: Rect;
+    }) => void;
+    openFile: (item: DriveItem, desktop?: Rect) => void;
+    closeWindow: (id: string) => void;
+    focusWindow: (id: string) => void;
+    minimizeWindow: (id: string) => void;
+    toggleMaximize: (id: string, desktop: Rect) => void;
+    restoreWindow: (id: string) => void;
+    moveWindow: (id: string, x: number, y: number) => void;
+    resizeWindow: (id: string, rect: Rect) => void;
+    navigateWindow: (id: string, path: string) => void;
+    setWindowViewMode: (id: string, mode: ViewMode) => void;
+    bumpRefresh: (path: string) => void;
+    resetWindows: () => void;
+    restoreViewMode: () => void;
+}
+export declare function createFinderStore(scope: string): FinderStoreApi;
+export { pathTitle };

package/dist/store.js

@@ -0,0 +1,228 @@
+import { nanoid } from "nanoid";
+import { proxy } from "valtio";
+const FOLDER_W = 720;
+const FOLDER_H = 480;
+const FILE_W = 560;
+const FILE_H = 520;
+function pathTitle(path) {
+    const name = path.split("/").filter(Boolean).at(-1);
+    return name || "根目录";
+}
+export function createFinderStore(scope) {
+    const viewModeKey = `flaredrive-finder-viewmode-${scope}`;
+    const store = proxy({
+        windows: [],
+        focusedId: null,
+        nextZ: 1,
+        spawnIndex: 0,
+        defaultViewMode: "list",
+        refreshSignal: {},
+    });
+    const spawnPos = (width, height, desktop) => {
+        const offset = (store.spawnIndex % 6) * 28;
+        store.spawnIndex += 1;
+        const baseX = 32 + offset;
+        const baseY = 24 + offset;
+        if (desktop) {
+            const maxX = Math.max(8, desktop.width - width - 8);
+            const maxY = Math.max(8, desktop.height - height - 8);
+            return { x: Math.min(baseX, maxX), y: Math.min(baseY, maxY) };
+        }
+        return { x: baseX, y: baseY };
+    };
+    const bringToFront = (win) => {
+        win.z = store.nextZ;
+        store.nextZ += 1;
+        store.focusedId = win.id;
+    };
+    const refocusTop = () => {
+        const top = [...store.windows]
+            .filter((w) => w.state !== "minimized")
+            .sort((a, b) => b.z - a.z)[0];
+        store.focusedId = top?.id ?? null;
+    };
+    const openFolder = (path, options = {}) => {
+        const clean = path.replace(/^\/+|\/+$/g, "");
+        if (!options.inNewWindow) {
+            const focused = store.windows.find((w) => w.id === store.focusedId && w.kind === "folder");
+            if (focused) {
+                focused.path = clean;
+                focused.title = pathTitle(clean);
+                if (focused.state === "minimized")
+                    focused.state = "normal";
+                bringToFront(focused);
+                return;
+            }
+        }
+        const pos = spawnPos(FOLDER_W, FOLDER_H, options.desktop);
+        const win = {
+            id: nanoid(8),
+            kind: "folder",
+            title: pathTitle(clean),
+            x: pos.x,
+            y: pos.y,
+            width: FOLDER_W,
+            height: FOLDER_H,
+            state: "normal",
+            z: store.nextZ,
+            path: clean,
+            viewMode: store.defaultViewMode,
+        };
+        store.nextZ += 1;
+        store.focusedId = win.id;
+        store.windows.push(win);
+    };
+    const openFile = (item, desktop) => {
+        const existing = store.windows.find((w) => w.kind === "file" && w.fileItem?.path === item.path);
+        if (existing) {
+            if (existing.state === "minimized")
+                existing.state = "normal";
+            bringToFront(existing);
+            return;
+        }
+        const pos = spawnPos(FILE_W, FILE_H, desktop);
+        const win = {
+            id: nanoid(8),
+            kind: "file",
+            title: item.name,
+            x: pos.x,
+            y: pos.y,
+            width: FILE_W,
+            height: FILE_H,
+            state: "normal",
+            z: store.nextZ,
+            fileItem: item,
+        };
+        store.nextZ += 1;
+        store.focusedId = win.id;
+        store.windows.push(win);
+    };
+    const closeWindow = (id) => {
+        const index = store.windows.findIndex((w) => w.id === id);
+        if (index === -1)
+            return;
+        store.windows.splice(index, 1);
+        if (store.focusedId === id)
+            refocusTop();
+    };
+    const focusWindow = (id) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win || store.focusedId === id)
+            return;
+        bringToFront(win);
+    };
+    const minimizeWindow = (id) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win)
+            return;
+        win.state = "minimized";
+        if (store.focusedId === id)
+            refocusTop();
+    };
+    const toggleMaximize = (id, desktop) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win)
+            return;
+        if (win.state === "maximized") {
+            if (win.prevRect) {
+                win.x = win.prevRect.x;
+                win.y = win.prevRect.y;
+                win.width = win.prevRect.width;
+                win.height = win.prevRect.height;
+            }
+            win.state = "normal";
+        }
+        else {
+            win.prevRect = {
+                x: win.x,
+                y: win.y,
+                width: win.width,
+                height: win.height,
+            };
+            win.x = 0;
+            win.y = 0;
+            win.width = desktop.width;
+            win.height = desktop.height;
+            win.state = "maximized";
+        }
+        bringToFront(win);
+    };
+    const restoreWindow = (id) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win)
+            return;
+        if (win.state === "minimized")
+            win.state = "normal";
+        bringToFront(win);
+    };
+    const moveWindow = (id, x, y) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win)
+            return;
+        win.x = x;
+        win.y = y;
+    };
+    const resizeWindow = (id, rect) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win)
+            return;
+        win.x = rect.x;
+        win.y = rect.y;
+        win.width = rect.width;
+        win.height = rect.height;
+    };
+    const navigateWindow = (id, path) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win || win.kind !== "folder")
+            return;
+        const clean = path.replace(/^\/+|\/+$/g, "");
+        win.path = clean;
+        win.title = pathTitle(clean);
+    };
+    const setWindowViewMode = (id, mode) => {
+        const win = store.windows.find((w) => w.id === id);
+        if (!win)
+            return;
+        win.viewMode = mode;
+        store.defaultViewMode = mode;
+        if (typeof window !== "undefined")
+            localStorage.setItem(viewModeKey, mode);
+    };
+    const bumpRefresh = (path) => {
+        const clean = path.replace(/^\/+|\/+$/g, "");
+        store.refreshSignal[clean] = (store.refreshSignal[clean] ?? 0) + 1;
+    };
+    const resetWindows = () => {
+        store.windows = [];
+        store.focusedId = null;
+        store.spawnIndex = 0;
+        store.refreshSignal = {};
+    };
+    const restoreViewMode = () => {
+        if (typeof window === "undefined")
+            return;
+        const saved = localStorage.getItem(viewModeKey);
+        if (saved === "grid" || saved === "list") {
+            store.defaultViewMode = saved;
+        }
+    };
+    return {
+        store,
+        viewModeKey,
+        openFolder,
+        openFile,
+        closeWindow,
+        focusWindow,
+        minimizeWindow,
+        toggleMaximize,
+        restoreWindow,
+        moveWindow,
+        resizeWindow,
+        navigateWindow,
+        setWindowViewMode,
+        bumpRefresh,
+        resetWindows,
+        restoreViewMode,
+    };
+}
+export { pathTitle };

package/dist/styles/source.css

@@ -0,0 +1 @@
+@source "../";

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export interface DriveItem {
+    name: string;
+    path: string;
+    size: number;
+    contentType: string;
+    modified: string;
+    isDirectory: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ziioapp/finder",
+  "version": "0.1.0",
+  "description": "Backend-agnostic multi-window Finder UI for ZiioApp",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./backend": {
+      "types": "./dist/backend.d.ts",
+      "import": "./dist/backend.js"
+    },
+    "./format": {
+      "types": "./dist/format.d.ts",
+      "import": "./dist/format.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./window-frame": {
+      "types": "./dist/components/window-frame.d.ts",
+      "import": "./dist/components/window-frame.js"
+    },
+    "./styles/source.css": "./dist/styles/source.css",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "lucide-react": "^1.16.0",
+    "nanoid": "^5.1.11",
+    "valtio": "^2.3.2"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.14",
+    "@ziioapp/ui": "^0.2.1",
+    "react": "^19.2.4",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "@ziioapp/ui": "^0.2.1",
+    "react": "^19.2.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "author": "ziioai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ziioai/ziioos.git",
+    "directory": "packages/finder"
+  },
+  "homepage": "https://github.com/ziioai/ziioos#readme",
+  "bugs": {
+    "url": "https://github.com/ziioai/ziioos/issues"
+  },
+  "keywords": [
+    "finder",
+    "file-manager",
+    "react",
+    "ziioapp"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "node ../../scripts/build-package.mjs"
+  }
+}