@brftech/filex-core 0.21.6 → 0.23.0

package/src/FileExplorer.vue

@@ -1419,8 +1419,167 @@ async function onToolbarAction(key: string) {
   await dispatchItemAction(key, sel);
 }
 
+// ─── desktop selective sync — "keep on this computer" ──────────────────
+// Present only when the desktop shell passes config.desktopSync; the web
+// admin and the embeds never see these entries. State is PULLED, not pushed:
+// the kept list is re-read as a menu opens, so the component needs no event
+// channel back to the shell and cannot go stale in a way that outlives one
+// right-click.
+const desktopSync = computed(() => props.config.desktopSync ?? null);
+const keptPairs = ref<Array<{ remote: string; local: string }>>([]);
+
+async function refreshKept(): Promise<void> {
+  if (!desktopSync.value) return;
+  try {
+    keptPairs.value = await desktopSync.value.kept();
+  } catch {
+    // Shell went away mid-call; a stale entry only mislabels a menu item.
+  }
+}
+
+/** The folder the engine is working on RIGHT NOW (null between runs). Drives
+ *  the ⟳ row badges and the bottom progress strip. */
+const keepActive = ref<{
+  remote: string;
+  phase: 'inventory' | 'plan' | 'transfer' | 'settling';
+  done: number;
+  total: number;
+} | null>(null);
+
+async function refreshKeepStatus(): Promise<void> {
+  const ds = desktopSync.value;
+  if (!ds?.status) return;
+  try {
+    keepActive.value = (await ds.status()).active ?? null;
+  } catch {
+    keepActive.value = null;
+  }
+}
+
+// The shell pokes on every engine output line — during a transfer that can be
+// several a second, and each refresh is an IPC round-trip. Trailing-edge
+// throttle: at most one refresh per 300ms, and the FINAL poke always lands,
+// so the strip cannot get stuck showing a finished transfer.
+let keepPokeTimer: ReturnType<typeof setTimeout> | null = null;
+// The shell holds the callback and only drops it on the NEXT mount, so a poke
+// can arrive after this instance is gone — pokes then set refs nothing reads.
+// Cheap to make explicit rather than rely on that being harmless.
+let keepAlive = true;
+function onKeepPoke(): void {
+  if (keepPokeTimer || !keepAlive) return;
+  keepPokeTimer = setTimeout(() => {
+    keepPokeTimer = null;
+    if (!keepAlive) return;
+    void refreshKeepStatus();
+    void refreshKept();
+  }, 300);
+}
+
+onMounted(() => {
+  void refreshKept();
+  void refreshKeepStatus();
+  desktopSync.value?.onChange?.(onKeepPoke);
+});
+onBeforeUnmount(() => {
+  keepAlive = false;
+  if (keepPokeTimer) {
+    clearTimeout(keepPokeTimer);
+    keepPokeTimer = null;
+  }
+});
+
+/** Adapter-qualified remote for a row. Virtual storage rows carry a bare
+ *  name (`docs`), real rows a wire path (`docs://reports`). */
+function keepRemoteOf(node: FileNode): string {
+  const p = String(node.path ?? '');
+  return p.includes('://') ? p.replace(/\/+$/, '') : `${p}://`;
+}
+
+type KeepState = 'none' | 'kept' | 'inherited' | 'partial';
+
+/** True when `child` lives strictly inside `parent` (both wire-form). */
+function remoteInside(child: string, parent: string): boolean {
+  if (parent.endsWith('://')) return child.startsWith(parent) && child !== parent;
+  return child === parent ? false : child.startsWith(parent + '/');
+}
+
+/** How `remote` relates to the kept set: exactly a pair, inside one
+ *  (inherited), an ancestor of some (partial), or unrelated. */
+function keepStateOf(remote: string): KeepState {
+  if (keptPairs.value.some((p) => p.remote === remote)) return 'kept';
+  if (keptPairs.value.some((p) => remoteInside(remote, p.remote))) return 'inherited';
+  if (keptPairs.value.some((p) => remoteInside(p.remote, remote))) return 'partial';
+  return 'none';
+}
+
+type KeepBadge = 'kept' | 'syncing' | 'cloud' | 'partial';
+
+/**
+ * The availability badge for one row: on this computer, being synced right
+ * now, holding kept items somewhere below (partial), or online-only. Every
+ * row gets one — that is the OneDrive/Drive grammar people already read —
+ * except the rows where it would be a lie or noise: trash, and the `.trash`
+ * row itself. `partial` is what saves the user from drilling into every
+ * folder to find out whether anything inside is on this computer.
+ */
+function keepBadgeFor(n: FileNode): KeepBadge | null {
+  if (!desktopSync.value || trashActive.value) return null;
+  if (n.basename === '.trash') return null;
+  const r = keepRemoteOf(n);
+  const act = keepActive.value;
+  if (act && (r === act.remote || remoteInside(r, act.remote) || remoteInside(act.remote, r))) {
+    return 'syncing';
+  }
+  const st = keepStateOf(r);
+  if (st === 'kept' || st === 'inherited') return 'kept';
+  if (st === 'partial') return 'partial';
+  return 'cloud';
+}
+
+/** Bottom strip: what to say while the engine works. */
+const keepStripLabel = computed<string>(() => {
+  const act = keepActive.value;
+  if (!act) return '';
+  const name = act.remote.endsWith('://')
+    ? act.remote.slice(0, -'://'.length)
+    : act.remote.slice(act.remote.lastIndexOf('/') + 1);
+  if (act.phase === 'transfer' && act.total > 0) {
+    return t('keep.strip_transfer', {
+      name,
+      done: String(act.done),
+      total: String(act.total),
+      pct: String(Math.min(100, Math.round((act.done * 100) / act.total))),
+    });
+  }
+  if (act.phase === 'settling') return t('keep.strip_settling', { name });
+  return t('keep.strip_inventory', { name });
+});
+
+const keepStripPercent = computed<number | null>(() => {
+  const act = keepActive.value;
+  if (!act || act.phase !== 'transfer' || act.total <= 0) return null;
+  return Math.min(100, Math.round((act.done * 100) / act.total));
+});
+
+/** Menu entries for one selected folder OR file, by its keep state. Empty
+ *  for multi-selections, trash, encrypted folders, or a web mount. */
+function keepActionsFor(sel: FileNode[]): ContextAction[] {
+  const ds = desktopSync.value;
+  const single = sel.length === 1 && (sel[0]?.type === 'dir' || sel[0]?.type === 'file');
+  if (!ds || !single || trashActive.value || e2eActive.value || sel[0]?.e2e === true) return [];
+  const st = keepStateOf(keepRemoteOf(sel[0]!));
+  return [
+    { divider: true, key: 'sep-keep', label: '' },
+    { key: 'keep-local', label: t('ctx.keep_local'), icon: '📌', hidden: st === 'kept' || st === 'inherited' },
+    { key: 'keep-online', label: t('ctx.keep_online'), icon: '☁', hidden: st !== 'kept' },
+    { key: 'keep-inherited', label: t('ctx.keep_inherited'), icon: '📌', disabled: true, hidden: st !== 'inherited' },
+    { key: 'keep-reveal', label: t('ctx.keep_reveal'), icon: '📂', hidden: st !== 'kept' && st !== 'inherited' },
+  ];
+}
+
 async function onContextTarget(node: FileNode, ev: MouseEvent) {
   ctxMode.value = 'selection';
+  void refreshKept(); // menu labels react if the kept set changed since last look
   if (!selection.has(node.path)) {
     selection.click(node.path);
     await nextTick();
@@ -1447,6 +1606,7 @@ function onCrumbContext(payload: { x: number; y: number; adapterPath: string; la
  * dispatchItemAction'a gider ve ctxMode==='pane' iken pane-route'lanır. */
 function onPaneContext(node: FileNode | null, ev: MouseEvent) {
   activePane.value = 'split';
+  void refreshKept();
   const sel = splitPaneRef.value?.selectedNodes() ?? [];
   // node=null (boş alana sağ-tık): seçimsiz menü (Yeni Klasör + Yapıştır).
   // Aksi halde pane seçimi (yoksa tıklanan node) hedeftir.
@@ -1507,6 +1667,9 @@ const contextActions = computed<ContextAction[]>(() => {
     return [
       { key: 'open', label: t('ctx.open'), icon: '↗' },
       { key: 'open-tab', label: t('ctx.open_new_tab'), icon: '⧉' } /* wiring:d1 */,
+      // A whole storage can be kept too — that IS the "sync everything"
+      // shape, and it is one pair, not one per subfolder.
+      ...keepActionsFor(sel),
     ];
   }
 
@@ -1571,6 +1734,7 @@ function selectionActionList(sel: FileNode[]): ContextAction[] {
     { key: 'paste', label: t('ctx.paste'), icon: '📋', hidden: !w, disabled: !clipboard.value.mode },
     { divider: true, key: 'sep-meta', label: '', hidden: !singleHasId },
     { key: 'tags', label: tagsLabel, icon: '🏷', hidden: !singleHasId, disabled: !singleHasId },
+    ...keepActionsFor(sel),
     { divider: true, key: 'sep2', label: '', hidden: !w },
     { key: 'delete', label: t('ctx.delete'), icon: '🗑', danger: true, hidden: !any || !w, disabled: !any },
   ];
@@ -1631,6 +1795,38 @@ async function dispatchItemAction(key: string, targets: FileNode[]) {
     case 'download':
       if (targets[0]) downloadFile(targets[0]);
       break;
+    case 'keep-local': {
+      const ds = desktopSync.value;
+      if (!ds || !targets[0]) break;
+      const remote = keepRemoteOf(targets[0]);
+      try {
+        await ds.keep(remote, targets[0].type === 'file' ? 'file' : 'dir');
+        await refreshKept();
+        // The shell may have shown its root-folder prompt and been cancelled —
+        // only claim success when the pair is really there now.
+        if (keepStateOf(remote) !== 'none') flashToast(t('keep.started'));
+      } catch (e) {
+        await refreshKept();
+        flashToast(`${t('keep.failed')}: ${String((e as Error)?.message ?? e)}`);
+      }
+      break;
+    }
+    case 'keep-online': {
+      const ds = desktopSync.value;
+      if (!ds || !targets[0]) break;
+      try {
+        await ds.unkeep(keepRemoteOf(targets[0]));
+      } catch {
+        // The shell owns the confirm dialog and reports its own failures.
+      }
+      await refreshKept();
+      break;
+    }
+    case 'keep-reveal': {
+      const ds = desktopSync.value;
+      if (ds && targets[0]) void ds.reveal(keepRemoteOf(targets[0]));
+      break;
+    }
     case 'convert':
       if (targets[0]) openConvert(targets[0]);
       break;
@@ -3417,6 +3613,7 @@ async function submitEncryptedFolder(payload: { name: string; password: string }
         :show-parent-path="!!searchQuery"
         :locale="locale"
         :loading="loading"
+        :keep-badge-for="desktopSync ? keepBadgeFor : undefined"
         :starred-ids="starredIds"
         :api-base="props.config.apiBase ?? ''"
         :auth-headers="() => buildAuthHeaders()"
@@ -3436,6 +3633,7 @@ async function submitEncryptedFolder(payload: { name: string; password: string }
         :show-parent-path="!!searchQuery"
         :locale="locale"
         :loading="loading"
+        :keep-badge-for="desktopSync ? keepBadgeFor : undefined"
         :thumb-src="thumbs.src"
         @click-card="(n, m) => selection.click(n.path, m)"
         @dbl-card="openNode"
@@ -3467,6 +3665,7 @@ async function submitEncryptedFolder(payload: { name: string; password: string }
          :key tab kimliğine bağlı — tab geçişinde pane kendi konumuyla temiz
          remount olur. -->
     <SecondaryPane
+      :keep-badge-for="desktopSync ? keepBadgeFor : undefined"
       v-if="splitVisible && activeSplit"
       ref="splitPaneRef"
       :key="'split-' + tabsActiveId"
@@ -3572,6 +3771,16 @@ async function submitEncryptedFolder(payload: { name: string; password: string }
       </svg>
     </button>
 
+    <!-- selective-sync progress: the folder the engine is moving RIGHT NOW.
+         Overlay, pointer-events none — status is never in the way of work. -->
+    <div v-if="keepActive" class="fe-keep-strip" role="status" aria-live="polite">
+      <span class="fe-keep-strip__icon" aria-hidden="true">⟳</span>
+      <span class="fe-keep-strip__label">{{ keepStripLabel }}</span>
+      <div v-if="keepStripPercent !== null" class="fe-keep-strip__bar" aria-hidden="true">
+        <div class="fe-keep-strip__fill" :style="{ width: keepStripPercent + '%' }"></div>
+      </div>
+    </div>
+
     <ContextMenu
       ref="ctxRef"
       :locale="locale"

package/src/components/GridView.vue

@@ -21,6 +21,9 @@ const props = defineProps<{
    *  root-relative and unauthenticated — a bare <img src> only works for the
    *  native same-origin SPA, so embedded hosts NEED this. null = icon. */
   thumbSrc?: (n: FileNode) => string | null;
+  /** Desktop selective sync: availability badge per tile. Absent on the
+   *  web — no badge renders at all. */
+  keepBadgeFor?: (n: FileNode) => 'kept' | 'syncing' | 'cloud' | 'partial' | null;
 }>();
 
 const emit = defineEmits<{
@@ -123,6 +126,13 @@ function parentDir(path: string): string {
 
 // Special rows keep their emoji (trash/storage are not file-TYPE icons);
 // everything else renders the SVG icon set from lib/fileIcons.
+function keepGlyph(b: 'kept' | 'syncing' | 'cloud' | 'partial'): string {
+  if (b === 'kept') return '\u2713';
+  if (b === 'syncing') return '\u27f3';
+  if (b === 'partial') return '\u25d0';
+  return '\u2601';
+}
+
 function specialEmojiFor(n: FileNode): string | null {
   if (n.basename === '.trash') return '🗑';
   if (n.mime_type === 'inode/storage') return '💾';
@@ -205,6 +215,13 @@ function snippetTitle(snippet: string): string {
       </div>
       <div class="fe-grid__label" :title="n.basename">
         {{ nodeDisplayName(n) }}
+        <span
+          v-if="keepBadgeFor && keepBadgeFor(n)"
+          :class="['fe-keepbadge', 'fe-keepbadge--' + keepBadgeFor(n)]"
+          :title="t('keep.badge_' + keepBadgeFor(n))"
+          role="img"
+          :aria-label="t('keep.badge_' + keepBadgeFor(n))"
+        >{{ keepGlyph(keepBadgeFor(n)!) }}</span>
       </div>
       <div
         v-if="showParentPath"

package/src/components/ListView.vue

@@ -39,6 +39,10 @@ const props = defineProps<{
   apiBase?: string;
   authHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
   authCredentials?: RequestCredentials;
+  /** Desktop selective sync: availability badge per row (kept on this
+   *  computer / syncing right now / online only). Absent on the web —
+   *  no badge renders at all. */
+  keepBadgeFor?: (n: FileNode) => 'kept' | 'syncing' | 'cloud' | 'partial' | null;
 }>();
 
 const emit = defineEmits<{
@@ -144,6 +148,13 @@ function specialEmojiFor(n: FileNode): string | null {
   return null;
 }
 
+function keepGlyph(b: 'kept' | 'syncing' | 'cloud' | 'partial'): string {
+  if (b === 'kept') return '\u2713';
+  if (b === 'syncing') return '\u27f3';
+  if (b === 'partial') return '\u25d0';
+  return '\u2601';
+}
+
 function isPinnedSpecial(n: FileNode): boolean {
   return n.basename === '.trash' || n.mime_type === 'inode/storage';
 }
@@ -397,6 +408,13 @@ const segments = computed<Segment[]>(() => {
               {{ nodeDisplayName(n) }}
               <!-- bul:s3 — content-match badge -->
               <span v-if="rowInContent(n)" class="fe-list__badge">{{ t('search.in_content') }}</span>
+              <span
+                v-if="keepBadgeFor && keepBadgeFor(n)"
+                :class="['fe-keepbadge', 'fe-keepbadge--' + keepBadgeFor(n)]"
+                :title="t('keep.badge_' + keepBadgeFor(n))"
+                role="img"
+                :aria-label="t('keep.badge_' + keepBadgeFor(n))"
+              >{{ keepGlyph(keepBadgeFor(n)!) }}</span>
             </span>
             <span
               v-if="showParentPath"

package/src/components/SecondaryPane.vue

@@ -58,6 +58,8 @@ const props = defineProps<{
   viewMode?: ViewMode;
   /** ui-fix — authenticated thumb resolver, forwarded to grid/gallery. */
   thumbSrc?: (n: FileNode) => string | null;
+  /** Desktop selective sync badge resolver, forwarded to the views. */
+  keepBadgeFor?: (n: FileNode) => 'kept' | 'syncing' | 'cloud' | 'partial' | null;
   /** ui-fix — mirror the main panel's virtual `.trash` row at storage root
    *  so both split panes list identical rows (no row-offset). Defaults on. */
   trashVisible?: boolean;
@@ -396,6 +398,7 @@ defineExpose({ reload, goUp, selectAll, openSelected, selectedNodes, getPath });
         :selected="selected"
         :locale="locale"
         :loading="loading"
+        :keep-badge-for="keepBadgeFor"
         @click-row="onViewClick"
         @dbl-row="onRowDbl"
         @context-row="onViewContext"
@@ -409,6 +412,7 @@ defineExpose({ reload, goUp, selectAll, openSelected, selectedNodes, getPath });
         :locale="locale"
         :loading="loading"
         :thumb-src="thumbSrc"
+        :keep-badge-for="keepBadgeFor"
         @click-card="onViewClick"
         @dbl-card="onRowDbl"
         @context-card="onViewContext"

package/src/locales/en.ts

@@ -23,6 +23,19 @@ export const en: Record<string, string> = {
   'ctx.cut': 'Cut',
   'ctx.show_hidden': 'Show hidden files',
   'ctx.hide_hidden': 'Hide hidden files',
+  'ctx.keep_local': 'Keep on this computer',
+  'ctx.keep_online': 'Keep online only',
+  'ctx.keep_reveal': 'Open local folder',
+  'ctx.keep_inherited': 'Kept on this computer with its parent',
+  'keep.started': 'Will be kept on this computer — sync started',
+  'keep.failed': 'Could not keep on this computer',
+  'keep.badge_kept': 'On this computer',
+  'keep.badge_syncing': 'Syncing…',
+  'keep.badge_cloud': 'Online only',
+  'keep.badge_partial': 'Contains items kept on this computer',
+  'keep.strip_transfer': 'Syncing {name} — {done}/{total} ({pct}%)',
+  'keep.strip_inventory': 'Syncing {name} — scanning the server…',
+  'keep.strip_settling': 'Syncing {name} — settling…',
   'ctx.paste': 'Paste',
   'ctx.info': 'Info',
   'ctx.duplicate': 'Duplicate',

package/src/locales/tr.ts

@@ -23,6 +23,19 @@ export const tr: Record<string, string> = {
   'ctx.cut': 'Kes',
   'ctx.show_hidden': 'Gizli dosyaları göster',
   'ctx.hide_hidden': 'Gizli dosyaları gizle',
+  'ctx.keep_local': 'Bilgisayarda tut',
+  'ctx.keep_online': 'Yalnızca çevrimiçi tut',
+  'ctx.keep_reveal': 'Yerel klasörü aç',
+  'ctx.keep_inherited': 'Üst klasörle bilgisayarda tutuluyor',
+  'keep.started': 'Bilgisayarda tutulacak — eşitleme başladı',
+  'keep.failed': 'Bilgisayarda tutulamadı',
+  'keep.badge_kept': 'Bilgisayarda',
+  'keep.badge_syncing': 'Eşitleniyor…',
+  'keep.badge_cloud': 'Yalnızca çevrimiçi',
+  'keep.badge_partial': 'İçinde bilgisayarda tutulanlar var',
+  'keep.strip_transfer': '{name} eşitleniyor — {done}/{total} (%{pct})',
+  'keep.strip_inventory': '{name} eşitleniyor — sunucu taranıyor…',
+  'keep.strip_settling': '{name} eşitleniyor — son durum kaydediliyor…',
   'ctx.paste': 'Yapıştır',
   'ctx.info': 'Bilgi',
   'ctx.duplicate': 'Kopyasını Oluştur',

package/src/styles/base.css

@@ -3928,3 +3928,83 @@ filex-explorer {
   }
 }
 /* === /ui-fix ========================================================= */
+
+/* ── selective sync (desktop shell only): availability badges + strip ──
+   The glyphs read in the OneDrive/Drive grammar: ✓ on this computer,
+   ⟳ being synced right now, ☁ online-only. Rendered only when the host
+   passes keepBadgeFor — the web admin and the embeds never show them. */
+.fe-keepbadge {
+  flex: 0 0 auto;
+  display: inline-block;
+  margin-left: 4px;
+  font-size: 11px;
+  line-height: 1;
+  vertical-align: middle;
+}
+.fe-keepbadge--kept {
+  color: var(--fe-keep-ok, #16a34a);
+}
+.fe-keepbadge--cloud {
+  color: var(--fe-text-muted);
+  opacity: 0.7;
+}
+.fe-keepbadge--partial {
+  color: var(--fe-keep-ok, #16a34a);
+  opacity: 0.85;
+}
+.fe-keepbadge--syncing {
+  color: var(--fe-primary);
+  animation: fe-keep-spin 1.2s linear infinite;
+}
+@keyframes fe-keep-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* Bottom overlay strip: progress of the folder being synced right now.
+   pointer-events none — it reports, it never blocks a click. */
+.fe-keep-strip {
+  position: absolute;
+  left: 12px;
+  right: 12px;
+  bottom: 10px;
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 12px;
+  border: 1px solid var(--fe-border);
+  border-radius: 10px;
+  background: var(--fe-bg-elev);
+  box-shadow: var(--fe-shadow-sm, 0 2px 6px rgba(0, 0, 0, 0.18));
+  font-size: 12.5px;
+  color: var(--fe-text-muted);
+  pointer-events: none;
+}
+.fe-keep-strip__icon {
+  font-size: 13px;
+  line-height: 1;
+  color: var(--fe-primary);
+  animation: fe-keep-spin 1.2s linear infinite;
+}
+.fe-keep-strip__label {
+  flex: 0 1 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.fe-keep-strip__bar {
+  flex: 1 1 80px;
+  min-width: 60px;
+  height: 4px;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--fe-primary) 18%, transparent);
+  overflow: hidden;
+}
+.fe-keep-strip__fill {
+  height: 100%;
+  border-radius: 999px;
+  background: var(--fe-primary);
+  transition: width 0.3s ease;
+}

package/src/styles/variables.css

@@ -17,6 +17,7 @@
   --fe-primary-hover: #2563eb;
   --fe-danger: #dc2626;
   --fe-danger-hover: #b91c1c;
+  --fe-keep-ok: #16a34a; /* selective-sync "on this computer" check */
   --fe-shadow: 0 10px 32px rgba(15, 23, 42, 0.14);
   --fe-shadow-sm: 0 2px 6px rgba(15, 23, 42, 0.08);
   --fe-radius: 8px;
@@ -65,6 +66,7 @@
   --fe-primary-hover: #3b82f6;
   --fe-danger: #f87171;
   --fe-danger-hover: #ef4444;
+    --fe-keep-ok: #4ade80;
   --fe-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
   --fe-shadow-sm: 0 2px 6px rgba(0, 0, 0, 0.25);
 }
@@ -85,6 +87,7 @@
     --fe-primary-hover: #3b82f6;
     --fe-danger: #f87171;
     --fe-danger-hover: #ef4444;
+    --fe-keep-ok: #4ade80;
     --fe-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
     --fe-shadow-sm: 0 2px 6px rgba(0, 0, 0, 0.25);
   }

package/src/types/ExplorerConfig.ts

@@ -308,6 +308,48 @@ export interface ExplorerConfig {
     driver?: string;
     readOnly?: boolean;
   }>;
+
+  /**
+   * Desktop-shell hook — selective sync ("keep on this computer").
+   *
+   * Present only when the explorer runs inside the filex desktop app; the
+   * shell passes functions that talk to its sync engine, and the explorer
+   * grows "Keep on this computer" / "Online only" entries on folder menus.
+   * Absent (web admin, embeds): nothing about it renders.
+   *
+   * Folders only, by design: the sync engine pairs directories, and a file
+   * rides along with the folder that holds it.
+   */
+  desktopSync?: {
+    /** Kept folders for the mounted account, adapter-qualified remotes. */
+    kept: () => Promise<Array<{ remote: string; local: string }>>;
+    /** Start keeping a folder — or, with kind 'file', a single file.
+     *  Resolves once the pair is registered (or the user cancelled the
+     *  shell's root-folder prompt — re-read `kept`). */
+    keep: (remote: string, kind: 'dir' | 'file') => Promise<void>;
+    /** Stop keeping. The SHELL owns the "what happens to the local copy"
+     *  question — it asks natively and may cancel; re-read `kept` after. */
+    unkeep: (remote: string) => Promise<void>;
+    /** Open the folder's local mirror in the OS file manager. */
+    reveal: (remote: string) => Promise<void>;
+    /** Live engine state, for the row badges and the bottom progress strip.
+     *  `active` is the folder being worked on right now — the engine walks
+     *  its pairs one at a time — or null between runs. */
+    status?: () => Promise<{
+      running: boolean;
+      lastError?: string | null;
+      active: {
+        remote: string;
+        phase: 'inventory' | 'plan' | 'transfer' | 'settling';
+        done: number;
+        total: number;
+      } | null;
+    }>;
+    /** Subscribe to "something about sync changed" pokes from the shell —
+     *  the explorer re-reads `kept` and `status` when poked. The shell keeps
+     *  ONE subscriber (the mounted explorer) and overwrites it on remount. */
+    onChange?: (cb: () => void) => void;
+  };
 }
 
 /** Component emits — the parent listens for these events. */