@cocoar/vue-ui 3.1.0 → 3.2.0-beta.11

package/skills/cocoar-vue-ui/references/components/file-explorer/index.md

@@ -0,0 +1,311 @@
+<!-- Generated from apps/docs/components/file-explorer/index.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# File Explorer (Preview)
+
+`@cocoar/vue-file-explorer-core` is the **headless engine** for a VSCode-style file/asset explorer in Vue 3 — the **data + coordination**, not a finished UI. A single composable, `useFileExplorer({store})`, drives a pluggable `AssetStore<T>` backend and returns every ref + op a file explorer needs (tree + tab state machine, selection, async loading, blob-URL leases, dirty tracking, conflict resolution). It ships **no layout** — you compose the chrome with [`@cocoar/vue-ui`](../panel-layout.md) (`CoarPanelLayout`, `CoarSplitPane`, `CoarTree`, …). A batteries-included, layouted `<CoarFileExplorer>` component — under the bare `@cocoar/vue-file-explorer` name — is planned on top.
+
+> **Tip: Mental model — engine, not UI**
+>
+> `useFileExplorer` is **headless**: it renders no editors, tabs, breadcrumbs, or layout — it returns reactive state + ops, and your view binds to `fe.*`. The composable IS the bus that wires the panels together: select in the tree → a tab opens → the editor and details panels react, all through one shared `fe.*` instance. For the **layout**, reach for the [panel-layout](../panel-layout.md) primitives; the demos below are worked examples to copy. A batteries-included `<CoarFileExplorer>` component is planned — it'll sit on exactly these pieces.
+
+```ts
+import {
+  useFileExplorer,
+  createInMemoryAssetStore,
+  type Asset,
+} from '@cocoar/vue-file-explorer-core';
+```
+
+The required peer is [`@cocoar/vue-ui`](../tree.md) for `CoarTree` + `CoarTreeNodeLabel`. `@cocoar/vue-script-editor` is **optional** — only pulled in if you want the Monaco-typed `language` field on the file-meta resolver.
+
+## Three building blocks
+
+| Piece | Role | Doc |
+|---|---|---|
+| [`useFileExplorer({store})`](./use-file-explorer.md) | The composable. Tree state + tab state machine + async bookkeeping + every imperative op. | reference |
+| [`AssetStore<T>`](./asset-store.md) | The data-plane contract a backend implements (HTTP, IndexedDB, in-memory, …). | contract |
+| [`createInMemoryAssetStore`](./in-memory-store.md) | Reference implementation with reactive latency / failure / lazy / conflict knobs for demos and tests. | knobs |
+
+## Full dispatch demo
+
+A realistic shell — tree, tab bar (with preview/pinned), breadcrumb, and a dispatched editor area that swaps between `CoarScriptEditor` (Monaco) for code, `CoarMarkdownEditor` (Milkdown) for markdown, and `CoarDocumentViewer` for images. Click around, edit anything, **Ctrl+S** saves.
+
+**Demo — `file-explorer/demos/FullDispatch.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <component :is="Demo" v-if="Demo" />
+    <div v-else class="fe-loading">Loading demo…</div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { onMounted, shallowRef, type Component } from 'vue';
+const Demo = shallowRef<Component | null>(null);
+onMounted(async () => {
+  const [editorWorkerMod, tsWorkerMod, jsonWorkerMod] = await Promise.all([
+    import('monaco-editor/esm/vs/editor/editor.worker?worker'),
+    import('monaco-editor/esm/vs/language/typescript/ts.worker?worker'),
+    import('monaco-editor/esm/vs/language/json/json.worker?worker'),
+  ]);
+  (self as unknown as { MonacoEnvironment: unknown }).MonacoEnvironment = {
+    getWorker(_id: string, label: string) {
+      if (label === 'typescript' || label === 'javascript') return new tsWorkerMod.default();
+      if (label === 'json') return new jsonWorkerMod.default();
+      return new editorWorkerMod.default();
+    },
+  };
+  const mod = await import('./_internal/FullDispatchImpl.vue');
+  Demo.value = mod.default;
+});
+</script>
+
+<style scoped>
+.fe-loading {
+  height: 560px;
+  display: flex; align-items: center; justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280); font-size: 13px;
+}
+</style>
+```
+
+Click a file to **preview** it (italic title) — clicking another file replaces the preview tab. **Double-click** to pin (italic clears). Editing a preview tab auto-pins it the moment it goes dirty — the impossible "italic + unsaved" state never exists.
+
+> **Tip: Persistent viewer config across file swaps**
+>
+> Open `logo.svg`, click the thumbnails toggle to open the left rail, then switch to `README.md` and back. The rail stays open. Same for any tool config you pass.
+>
+> That's because in the demo, `viewerSidebarOpen` / `viewerAnnotationsPanelOpen` / `viewerTools` live as refs **outside** the editor `v-if` branch — they're consumer-owned state, just passed into `CoarDocumentViewer` via `v-model` (for the panel toggles) and `:tools` (for toolbar config). When you switch from `.md` (Milkdown) back to `.svg` (DocumentViewer), the viewer is freshly mounted but the props it sees on mount are the persisted values — so the panel comes up open, the same tools are configured. No additional API needed on `useFileExplorer` — the shell owns it.
+
+## Minimal shell
+
+Same composable, no heavy editors — useful as a starting point or for plain-text use cases:
+
+**Demo — `file-explorer/demos/BasicUsage.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <component :is="Demo" v-if="Demo" />
+    <div v-else class="fe-loading">Loading demo…</div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { onMounted, shallowRef, type Component } from 'vue';
+
+const Demo = shallowRef<Component | null>(null);
+onMounted(async () => {
+  const mod = await import('./_internal/BasicUsageImpl.vue');
+  Demo.value = mod.default;
+});
+</script>
+
+<style scoped>
+.fe-loading {
+  height: 360px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280);
+  font-size: 13px;
+}
+</style>
+```
+
+The composable returns refs (`rootNodes`, `selectedId`, `expanded`, `openTabs`, `activeTab`, `loadingNodes`, `savingNodes`, `breadcrumbPath`) and ops (`openFile`, `saveTab`, `closeTab`, `addFolder`, `addFiles`, `deleteNode`, `moveNode`, `rename`, `reorderTab`, …). Wire whichever you need into your shell.
+
+> **Tip: Where's the `<CoarFileExplorer>` component?**
+>
+> Planned — and reserved under the bare `@cocoar/vue-file-explorer` name. It'll be built on these exact pieces: `useFileExplorer` + the [panel-layout](../panel-layout.md) primitives + `CoarTree`. The engine ships first because the **layout** is the part consumers most want to own (sidebar arrangement, tab bar styling, editor dispatch, context-menu shape); the hard-to-get-right bits (placeholder-then-fill open, optimistic rollback, blob-URL lifecycle, beforeunload warning, drag-to-reorder tabs) already live in the engine.
+
+## Details panel
+
+The explorer hands you the **data** for a details / info panel; **where** it renders is your layout's call. `useFileExplorer` exposes **`selectedAsset`** (the selected node, resolved reactively from `selectedId`) and **`describeAsset(asset)`** (its framework-known property rows). Drop the panel below the tree, into a [`CoarPanelLayout`](../panel-layout.md) region — wherever.
+
+**Demo — `file-explorer/demos/InfoPanel.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <component :is="Demo" v-if="Demo" />
+    <div v-else class="fe-loading">Loading demo…</div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { onMounted, shallowRef, type Component } from 'vue';
+
+const Demo = shallowRef<Component | null>(null);
+onMounted(async () => {
+  const mod = await import('./_internal/InfoPanelImpl.vue');
+  Demo.value = mod.default;
+});
+</script>
+
+<style scoped>
+.fe-loading {
+  height: 360px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280);
+  font-size: 13px;
+}
+</style>
+```
+
+`describeAsset` returns only what the framework can know from the `Asset` shape + resolved file-meta — **Name, Type, Language** (script files), **Extension**, and **Path**:
+
+```ts
+const fe = useFileExplorer({ store });
+// fe.selectedAsset: Readonly<Ref<Asset<T> | null>>
+// fe.describeAsset(asset) → [{ key, label, value }, …]
+```
+
+```vue
+<dl v-if="fe.selectedAsset.value">
+  <div v-for="p in fe.describeAsset(fe.selectedAsset.value)" :key="p.key">
+    <dt>{{ p.label }}</dt><dd>{{ p.value }}</dd>
+  </div>
+</dl>
+```
+
+Domain fields (size, modified date, author, …) live in your generic `payload<T>` — the framework can't know them, so **append your own rows**: `[...fe.describeAsset(asset), ...myPayloadRows(asset)]`. Need full control? Skip `describeAsset` and build the panel straight off `selectedAsset`.
+
+> **Tip: Resizable tree-over-details sidebar**
+>
+> Want the tree stacked above the details panel with a draggable divider (VS-Code style)? Nest a [`CoarSplitPane`](../panel-layout.md) in your sidebar — tree in `#first`, the `selectedAsset` / `describeAsset` panel in `#second`. See the [panel layout](../panel-layout.md) docs.
+
+## Lazy mode
+
+Stores that implement `loadChildren(parentId)` opt into lazy loading. The composable detects the capability automatically — no flag needed.
+
+**Demo — `file-explorer/demos/LazyMode.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <component :is="Demo" v-if="Demo" />
+    <div v-else class="fe-loading">Loading demo…</div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { onMounted, shallowRef, type Component } from 'vue';
+const Demo = shallowRef<Component | null>(null);
+onMounted(async () => {
+  const mod = await import('./_internal/LazyModeImpl.vue');
+  Demo.value = mod.default;
+});
+</script>
+
+<style scoped>
+.fe-loading {
+  height: 320px; display: flex; align-items: center; justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280); font-size: 13px;
+}
+</style>
+```
+
+`hasChildren` hints control which folders show a chevron before their kids load. `loadingNodes` exposes the per-row spinner state so consumers can swap icon → spinner during a fetch.
+
+## Conflict policies
+
+Uploads and creates run through a per-store conflict policy. Default `'rename'` mirrors Finder / VSCode auto-suffixing (`foo.txt` → `foo (2).txt`).
+
+**Demo — `file-explorer/demos/ConflictPolicies.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <component :is="Demo" v-if="Demo" />
+    <div v-else class="fe-loading">Loading demo…</div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { onMounted, shallowRef, type Component } from 'vue';
+const Demo = shallowRef<Component | null>(null);
+onMounted(async () => {
+  const mod = await import('./_internal/ConflictPoliciesImpl.vue');
+  Demo.value = mod.default;
+});
+</script>
+
+<style scoped>
+.fe-loading {
+  height: 320px; display: flex; align-items: center; justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280); font-size: 13px;
+}
+</style>
+```
+
+`move` and `rename` deliberately **bypass** the policy — those are explicit user intent, not file additions, so silently changing the requested name would be surprising.
+
+## Sort modes
+
+Sibling ordering lives on the composable (not the store), because filesystem backends can't persist per-entry order. Pick one of three built-in strategies or pass a comparator.
+
+**Demo — `file-explorer/demos/SortModes.vue`**
+
+```vue
+<template>
+  <ClientOnly>
+    <component :is="Demo" v-if="Demo" />
+    <div v-else class="fe-loading">Loading demo…</div>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { onMounted, shallowRef, type Component } from 'vue';
+const Demo = shallowRef<Component | null>(null);
+onMounted(async () => {
+  const mod = await import('./_internal/SortModesImpl.vue');
+  Demo.value = mod.default;
+});
+</script>
+
+<style scoped>
+.fe-loading {
+  height: 320px; display: flex; align-items: center; justify-content: center;
+  color: var(--coar-text-neutral-tertiary, #6b7280); font-size: 13px;
+}
+</style>
+```
+
+| Mode | Behavior |
+|---|---|
+| `'folders-first'` (default) | Folders alphabetical, then files alphabetical — VSCode / Windows Explorer pattern. |
+| `'alphabetical'` | All entries mixed alphabetical — Finder pattern. |
+| `'manual'` | Array order = visual order. Drop-between-siblings positions persist via `store.move(id, parentId, position)`. |
+| `(a, b) => number` | Custom comparator (e.g. by extension, by mtime). |
+
+In any non-manual mode the composable silently drops the `position` argument when forwarding to `store.move()` — the comparator decides the final position after the parent change. `api.reorderable: Ref<boolean>` is reactive, so a toolbar can flip drag modes at runtime.
+
+## Architecture
+
+```
+useFileExplorer({store})
+├── AssetStore<T>                           ← your backend
+│     loadTree / loadChildren / loadContent
+│     createFolder / createFile / uploadFile
+│     save / rename / delete / move
+├── tree state                              ← rootNodes, selectedId, expanded
+├── tab state machine                       ← openTabs, activeTab, dirty, pin/preview
+├── async state                             ← loadingNodes, savingNodes
+├── blob-URL leases                         ← revoked on delete + unmount
+├── beforeunload warning                    ← active while any tab is dirty
+└── 3-stage file-meta fallback              ← asset.editor → getFileMeta → ext heuristic
+```
+
+The composable knows nothing about HTTP / IndexedDB / multipart — the `AssetStore<T>` contract is the seam. Swap implementations without touching the view.
+
+## What's next
+
+| Page | Covers |
+|------|--------|
+| [`useFileExplorer`](./use-file-explorer.md) | Options, return surface, tab state machine, navigation helpers, lifecycle |
+| [`AssetStore<T>` contract](./asset-store.md) | Every method's signature + semantics, conflict pipeline, lazy opt-in, error funnel |
+| [In-memory store](./in-memory-store.md) | `createInMemoryAssetStore` knobs — latency / failure / sort / lazy / conflict |

package/skills/cocoar-vue-ui/references/components/file-explorer/use-file-explorer.md

@@ -0,0 +1,300 @@
+<!-- Generated from apps/docs/components/file-explorer/use-file-explorer.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# useFileExplorer
+
+`useFileExplorer<T>({store, ...})` is the composable. It wires a configured [`AssetStore<T>`](./asset-store.md) into reactive tree + tab state, owns the async / dirty / blob-URL bookkeeping, and returns every ref and op a file-explorer shell needs.
+
+```ts
+import {
+  useFileExplorer,
+  type UseFileExplorerOptions,
+  type UseFileExplorerReturn,
+  type OpenTab,
+} from '@cocoar/vue-file-explorer-core';
+```
+
+## Options
+
+```ts
+interface UseFileExplorerOptions<T = unknown> {
+  store: AssetStore<T>;
+  onError?: (op: AssetOp, err: unknown, ctx: AssetOpContext) => void;
+  getFileMeta?: (asset: Asset<T>) => FileMeta | null;
+  confirm?: (message: string) => boolean;
+  initialExpandedIds?: readonly string[];
+  sortMode?: MaybeRefOrGetter<SortMode<T>>;
+}
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `store` | _required_ | Anything implementing [`AssetStore<T>`](./asset-store.md). The single seam between view and backend. |
+| `onError` | _no-op_ | Single funnel for every store rejection. The composable has already rolled back by the time this fires. |
+| `getFileMeta` | _none_ | Stage-2 of the file-meta fallback chain. Returns `null` to fall through to the extension heuristic. |
+| `confirm` | `window.confirm` | Used by `closeTab` / `closeOthers` / `closeToRight` / `closeAll` to confirm discarding dirty tabs. Override for custom dialogs. |
+| `initialExpandedIds` | top-level folders (eager) / `[]` (lazy) | Folder ids to seed `expanded` with. Defaults to root folders in eager mode so the user sees content immediately; defaults to empty in lazy mode so the canonical click-to-expand UX appears. |
+| `sortMode` | `'folders-first'` | Sibling ordering strategy. `MaybeRefOrGetter` so a toolbar can flip it live. See [sort modes](./index.md#sort-modes). |
+
+## Return surface
+
+The return is organized into four groups: tree state, tab state, ops, navigation.
+
+### Tree state
+
+```ts
+readonly assets: Readonly<Ref<readonly Asset<T>[]>>;
+readonly rootNodes: Readonly<Ref<readonly Asset<T>[]>>;
+selectedId: Ref<string | null>;
+readonly selectedAsset: Readonly<Ref<Asset<T> | null>>;
+expanded: Ref<Set<string>>;
+readonly loading: Readonly<Ref<boolean>>;
+readonly loadingNodes: Readonly<Ref<ReadonlySet<string>>>;
+readonly savingNodes: Readonly<Ref<ReadonlySet<string>>>;
+readonly reorderable: Readonly<Ref<boolean>>;
+```
+
+| Ref | Notes |
+|---|---|
+| `assets` | Flat reactive list — the store's underlying projection. Read-only from the consumer's perspective. |
+| `rootNodes` | Already filtered + sorted children of `null`. Pass directly to `<CoarTree :nodes>`. |
+| `selectedId` | Two-way. Single-click on a row sets this; a watcher then opens the file as a preview tab. |
+| `selectedAsset` | Read-only. `selectedId` resolved to the `Asset` (or `null`). Pair with `describeAsset` for a [details panel](./index.md#details-panel). |
+| `expanded` | Two-way `Set<string>` of expanded folder ids. Lazy loading is driven by CoarTree's `loadChildren` hook (bind `:load-children="fe.loadChildren"`) — the tree fires the fetch on first expand. |
+| `loading` | `true` during the **initial** `store.loadTree()` call only. Per-file content loads live on `loadingNodes`; per-folder lazy loads are owned by the tree (`isLoading` slot prop). Stays `false` for stores that surface their own reactive `_assets`. |
+| `loadingNodes` | Per-id Set of files being `loadContent`-fetched. (Folder lazy-loads moved to CoarTree's per-row `isLoading` slot prop.) Bind to row-icon → spinner swap. |
+| `savingNodes` | Per-id Set: any in-flight save / rename / delete / move. Same spinner channel as `loadingNodes`. |
+| `reorderable` | `true` when `sortMode === 'manual'`. Reactive — read it in your CoarTree wiring to gate drop-between-siblings. |
+
+### CoarTree wiring helpers
+
+```ts
+getId: (a: Asset<T>) => string;
+getChildren: (a: Asset<T>) => readonly Asset<T>[] | undefined;
+getLabel: (a: Asset<T>) => string;
+isExpandable: (a: Asset<T>) => boolean;
+loadChildren?: (node: Asset<T>) => Promise<void>; // lazy stores only — bind to <CoarTree :load-children>
+```
+
+These mirror `<CoarTree>`'s prop signatures so you can pass them straight through:
+
+```vue
+<CoarTree
+  :nodes="fe.rootNodes.value"
+  :get-id="fe.getId"
+  :get-children="fe.getChildren"
+  :get-label="fe.getLabel"
+  :is-expandable="fe.isExpandable"
+  :load-children="fe.loadChildren"
+  v-model:expanded="fe.expanded.value"
+  v-model:selected="fe.selectedId.value"
+  draggable
+  renamable
+  @activate="fe.activateNode"
+  @rename="({ node, newName }) => fe.rename(node.id, newName)"
+  @node-move="fe.moveNode"
+/>
+```
+
+`isExpandable` returns `false` for folders the store reports as `hasChildren: false` — keeps the chevron off known-empty folders in lazy mode.
+
+For **lazy stores**, bind `:load-children="fe.loadChildren"` (`undefined` for eager stores, so the binding is a no-op there). CoarTree calls it on first expand of an unloaded folder and owns the loading state (`isLoading` slot prop), the error state (`hasError` + `@load-error`) and retry (`api.reloadChildren`); the composable just supplies the fetch body and caches loaded folders so re-expand never re-fetches. Render the spinner where you like from `isLoading` (e.g. swap the row icon) and pass `hide-loading-spinner` to drop the tree's built-in chevron spinner. See the [tree lazy-loading docs](../tree.md#lazy-loading-async-children). Lazy-load failures reach **both** `onError('loadChildren', …)` (log/toast) and the tree's `@load-error` / `hasError` (row UX) — pick one channel for user-facing messaging to avoid duplicates.
+
+### Tab state
+
+```ts
+readonly openTabs: Readonly<Ref<readonly OpenTab[]>>;
+activeId: Ref<string | null>;
+readonly activeTab: Readonly<Ref<OpenTab | null>>;
+readonly anyDirty: Readonly<Ref<boolean>>;
+isDirty: (tab: OpenTab) => boolean;
+setContent: (id: string, content: string) => void;
+
+interface OpenTab {
+  id: string;
+  name: string;
+  editor: FileEditor;
+  language?: CoarScriptEditorLanguage;
+  content: string;          // current editor buffer
+  savedContent: string;     // last persisted — content !== savedContent ⇒ dirty
+  pinned: boolean;          // false = preview (italic, replaced on next preview)
+}
+```
+
+The tab state machine implements the VSCode pattern:
+
+| Trigger | Result |
+|---|---|
+| Single-click on a file row | Push a **preview** tab (italic title). At most one preview exists at a time — opening another preview replaces it. |
+| Double-click / Enter / "Open" menu | Open as **pinned**. Existing previews are upgraded in place. |
+| User edits → `setContent` differs from `savedContent` | Auto-pin the tab. Eliminates the impossible "italic + dirty" state. |
+| `closeTab` while dirty | Calls `options.confirm` ("Discard unsaved changes to '{name}'?"). |
+| `closeTab` while `savingNodes.has(id)` | Bails — closing would orphan the in-flight save. |
+
+### Imperative ops
+
+```ts
+// CRUD — optimistic; resolve when the backend confirms
+addFolder(parentId: string | null, name: string): Promise<Asset<T> | null>;
+addFiles(parentId: string | null, files: FileList | readonly File[]): Promise<void>;
+deleteNode(asset: Asset<T>): Promise<void>;
+move(id: string, newParentId: string | null, position?: number): Promise<void>;
+moveNode(e: CoarTreeNodeMoveEvent<Asset<T>>): Promise<void>;
+rename(id: string, newName: string): Promise<void>;
+refresh(folderId?: string | null): Promise<void>;
+
+// Tab ops
+openFile(asset: Asset<T>, opts?: { pinned: boolean }): Promise<void>;
+activateNode(asset: Asset<T>): void;          // dblclick / Enter — opens pinned
+saveTab(id: string): Promise<boolean>;
+saveActive(): Promise<void>;
+closeTab(id: string): void;
+closeOthers(keepId: string): void;
+closeToRight(anchorId: string): void;
+closeAll(): void;
+pinTab(id: string): void;
+unpinTab(id: string): void;
+reorderTab(sourceId: string, targetId: string, position: 'before' | 'after'): void;
+```
+
+Notes on the trickier ones:
+
+- **`addFolder`** is **optimistic**: a temp node is inserted immediately, then reconciled to the backend's real id on resolve (rolled back on error). Pairs with [`<CoarTree>`'s `startCreate`](../tree.md#inline-create) so the draft → real-node handoff has no flicker. (Stores that surface their own reactive `_assets` skip the temp node — their own mutation is the source.)
+- **`addFiles`** is the OS-drop entry point. The composable derives content per file (text or `URL.createObjectURL` for PDF / image), calls `store.uploadFile()`, then `store.save(id, content)` **if the store has `save`**. The merged node is stamped with the target `parentId`, so a folder-filtered grid shows it immediately even if the store's returned asset omitted it. Blob URLs are tracked and revoked on delete + unmount.
+- **`move`** is the plain programmatic move (optimistic + rollback) for sources that aren't a tree drag — a "move to folder" `<select>`, a grid card dropped on a folder row, an undo command. `newParentId: null` moves to the root; `position` (an index within the new parent's children) is honored only in `'manual'` sort mode. **`moveNode`** delegates to it.
+- **`moveNode`** consumes `<CoarTree>`'s `CoarTreeNodeMoveEvent`. For `position: 'inside'`, it auto-expands the target folder. For `'before' / 'after'`, it forwards a computed index only when `reorderable.value`.
+- **`openFile`** is the placeholder-then-fill flow. The placeholder tab is pushed + activated immediately; on `loadContent` rejection the placeholder rolls back so the user isn't stranded. **Browse-only stores** (no `loadContent`) make this a no-op — no editor tabs open, and the single-click-preview watcher stays quiet.
+- **`activateNode`** is meant for `<CoarTree @activate>`. Files open pinned; folders are a no-op (CoarTree itself toggles expansion).
+- **`reorderTab`** is for drag-to-reorder. No-op on self-drop or unknown ids; pinned status is preserved on the moved tab.
+- **`refresh()`** re-runs `store.loadTree()` (or `store.loadChildren(folderId)` in lazy mode when given a folder id). Use it when upstream state can change out-of-band — a SignalR push from the backend, another tab uploading a file, a server-side retention sweep. No-op for stores that surface a reactive `_assets` directly: those are already live.
+
+### Navigation
+
+```ts
+revealInTree(id: string, focusNode?: (id: string) => void): void;
+readonly breadcrumbPath: Readonly<Ref<readonly string[]>>;
+pathOf(id: string): string[];
+fileMeta(asset: Asset<T>): FileMeta | null;
+describeAsset(asset: Asset<T>): AssetProperty[]; // { key, label, value }
+```
+
+| Helper | Notes |
+|---|---|
+| `revealInTree` | Walks the parentId chain, expands every ancestor in one batch, sets `selectedId`, then calls `focusNode?.(id)` after Vue flushes. Pass the tree's `api.focusNode` if you have it. |
+| `breadcrumbPath` | Name-path of the **active tab**. Drives the editor-area breadcrumb. |
+| `pathOf(id)` | Name-path of any asset. Used for quick-open / recent-files matchers. |
+| `fileMeta(asset)` | Runs the 3-stage fallback. Returns `null` for unrecognised binary types — caller skips with a warning. |
+| `describeAsset(asset)` | Framework-known property rows (Name, Type, Language, Extension, Path) for a [details panel](./index.md#details-panel). Append your own `payload`-derived rows. Pure helper also exported as `buildAssetProperties`. |
+
+## Persistent viewer config across file swaps
+
+When the consumer's shell mounts different editors via `v-if` based on `activeTab.editor`, each editor component is freshly mounted on every editor-type swap (e.g. `.md` → `.ts` → `.md` unmounts + remounts Monaco the second time). Any internal editor state — Monaco's scroll position, `CoarDocumentViewer`'s sidebar open / closed, Milkdown's toolbar collapse — **resets on remount** unless the consumer's shell holds that state as refs and passes them in.
+
+The cleanest pattern: hold whatever you want to persist as refs **outside the `v-if` branch**, bind them via `v-model` or pass them via props.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CoarDocumentViewer, type CoarDocumentViewerTool } from '@cocoar/vue-document-viewer';
+
+// These live in the shell, not inside the v-if branch — they survive editor swaps.
+const viewerSidebarOpen = ref(false);
+const viewerAnnotationsPanelOpen = ref(false);
+const viewerTools: CoarDocumentViewerTool[] = [
+  'sidebar-toggle', 'annotations-panel', 'separator',
+  'zoom-out', 'zoom-reset', 'zoom-in', 'separator',
+  'fit-width', 'fit-page',
+];
+</script>
+
+<template>
+  <CoarDocumentViewer
+    v-if="fe.activeTab.value?.editor === 'image' && imageSrc"
+    :source="imageSrc"
+    :tools="viewerTools"
+    :show-thumbnails="true"
+    :show-annotations-panel="true"
+    v-model:sidebar-open="viewerSidebarOpen"
+    v-model:annotations-panel-open="viewerAnnotationsPanelOpen"
+  />
+</template>
+```
+
+> **Tip: This is shell-level state, not composable-level**
+>
+> The composable deliberately knows nothing about editors — `useFileExplorer` doesn't render them or hold their config. That keeps it independent of any specific editor package, and lets every consumer's shell define its own dispatch logic (which editor for which file type, fall-through to plain text, custom editors for proprietary asset payload types, …). The trade-off: editor persistence is a shell concern. The pattern above is the canonical way to handle it.
+
+This works for every editor: hold a Monaco view-state ref outside the `v-if` and restore it in `onMounted`; hold a Milkdown collapsed-toolbar boolean outside and pass it via prop; hold the position memory ref outside and bind it to `v-model:position`. The composable doesn't care — its job is the tree + tab state, not the editor's internals.
+
+## Lifecycle
+
+- **Mount — the tree loads itself.** `useFileExplorer` calls `store.loadTree()` automatically on mount (it kicks off the fetch synchronously during setup; `loading` is your "populating" signal). **You don't need a manual `fe.refresh()` in `onMounted`** — that would be a redundant second fetch. Reserve `refresh()` for out-of-band changes (server push, another tab mutating, retention sweep). Stores that surface their own reactive `_assets` (the in-memory impl) are live from creation, so the auto-load is a no-op for them.
+- **Lazy children** — Lazy loading is driven by CoarTree's `loadChildren` hook (bind `:load-children="fe.loadChildren"`): the tree fires the fetch on first expand and on mount for any seeded `initialExpandedIds` (cascading as parents publish). The composable supplies only the fetch body and caches loaded folders so re-expand never re-fetches.
+- **Eager open** — Single-click `selectedId` change is watched; file selections fire `openFile(file, { pinned: false })`.
+- **Unmount** — `onScopeDispose` removes the `beforeunload` listener and revokes every blob URL the composable owns. Consumer doesn't need to clean up.
+- **`beforeunload`** — Active while `anyDirty.value` is true. Browser shows its native "leave site?" prompt.
+
+## Example consumer shell
+
+A minimal shell — tree + breadcrumb + a single-tab editor area — to show what the composable's surface looks like in practice:
+
+```vue
+<script setup lang="ts">
+import {
+  createInMemoryAssetStore,
+  useFileExplorer,
+  type Asset,
+} from '@cocoar/vue-file-explorer-core';
+import { CoarTree, CoarTreeNodeLabel, CoarBreadcrumb, CoarBreadcrumbItem } from '@cocoar/vue-ui';
+
+const seed: Asset[] = [
+  { id: 's', name: 'src', kind: 'folder', parentId: null },
+  { id: 'u', name: 'utils.ts', kind: 'file', parentId: 's' },
+];
+const store = createInMemoryAssetStore({
+  initialTree: seed,
+  initialContent: { u: 'export const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));' },
+});
+const fe = useFileExplorer({
+  store,
+  onError: (op, err) => console.warn(`[file-explorer] ${op}:`, err),
+});
+</script>
+
+<template>
+  <div class="shell">
+    <aside>
+      <CoarTree
+        :nodes="fe.rootNodes.value"
+        :get-id="fe.getId"
+        :get-children="fe.getChildren"
+        :get-label="fe.getLabel"
+        :is-expandable="fe.isExpandable"
+        :load-children="fe.loadChildren"
+        v-model:expanded="fe.expanded.value"
+        v-model:selected="fe.selectedId.value"
+        renamable
+        @activate="fe.activateNode"
+        @rename="({ node, newName }) => fe.rename(node.id, newName)"
+      >
+        <template #default="{ node }">
+          <CoarTreeNodeLabel :label="node.name" />
+        </template>
+      </CoarTree>
+    </aside>
+    <main>
+      <CoarBreadcrumb v-if="fe.activeTab.value">
+        <CoarBreadcrumbItem v-for="seg in fe.breadcrumbPath.value" :key="seg">
+          {{ seg }}
+        </CoarBreadcrumbItem>
+      </CoarBreadcrumb>
+      <textarea
+        v-if="fe.activeTab.value"
+        :value="fe.activeTab.value.content"
+        @input="e => fe.setContent(fe.activeTab.value!.id, (e.target as HTMLTextAreaElement).value)"
+      />
+    </main>
+  </div>
+</template>
+```
+
+The full POC (`apps/playground/src/views/FileExplorerPocView.vue` — ~1280 LoC) wires every feature: tab bar with drag-to-reorder, context menus, `Ctrl+P` quick-open, simulator panel for latency / failure / sort / conflict, editor dispatch across Monaco / Milkdown / `CoarDocumentViewer`, OS file drop, reveal-in-tree. Treat it as the worked reference.