@brftech/filex-core 0.1.83 → 0.2.0

package/src/components/GridView.vue

@@ -5,6 +5,7 @@
 import type { FileNode } from '../types/FileNode';
 import type { LocaleCode } from '../types/ExplorerConfig';
 import { useLocale } from '../composables/useLocale';
+import { fileIconSvg } from '../lib/fileIcons';
 
 const props = defineProps<{
   files: FileNode[];
@@ -101,20 +102,12 @@ function parentDir(path: string): string {
   return stripped.slice(0, idx);
 }
 
-function iconFor(n: FileNode): string {
+// Special rows keep their emoji (trash/storage are not file-TYPE icons);
+// everything else renders the SVG icon set from lib/fileIcons.
+function specialEmojiFor(n: FileNode): string | null {
   if (n.basename === '.trash') return '🗑';
   if (n.mime_type === 'inode/storage') return '💾';
-  if (n.type === 'dir') return '📁';
-  const e = (n.extension || '').toLowerCase();
-  if (['jpg', 'jpeg', 'png', 'webp', 'gif', 'bmp', 'svg'].includes(e)) return '🖼';
-  if (['mp4', 'webm', 'mov', 'mkv'].includes(e)) return '🎞';
-  if (['mp3', 'wav', 'flac', 'ogg'].includes(e)) return '🎵';
-  if (e === 'pdf') return '📕';
-  if (['doc', 'docx', 'odt'].includes(e)) return '📄';
-  if (['xls', 'xlsx', 'csv'].includes(e)) return '📊';
-  if (['ppt', 'pptx'].includes(e)) return '📽';
-  if (['zip', 'tar', 'gz', '7z'].includes(e)) return '🗜';
-  return '📎';
+  return null;
 }
 </script>
 
@@ -156,7 +149,9 @@ function iconFor(n: FileNode): string {
           loading="lazy"
           draggable="false"
         />
-        <span v-else class="fe-grid__icon">{{ iconFor(n) }}</span>
+        <span v-else-if="specialEmojiFor(n)" class="fe-grid__icon">{{ specialEmojiFor(n) }}</span>
+        <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
+        <span v-else class="fe-grid__icon fe-grid__icon--svg" v-html="fileIconSvg(n)"></span>
       </div>
       <div class="fe-grid__label" :title="n.basename">
         {{ nodeDisplayName(n) }}

package/src/components/ListView.vue

@@ -6,10 +6,12 @@
  * just emit the events and let FileExplorer.vue handle them uniformly
  * across List and Grid.
  */
-import { computed } from 'vue';
+import { computed, ref } from 'vue';
 import type { FileNode } from '../types/FileNode';
 import type { LocaleCode } from '../types/ExplorerConfig';
 import { useLocale } from '../composables/useLocale';
+import { fileIconSvg } from '../lib/fileIcons';
+import { matchedInContent, snippetSegments } from '../lib/snippet'; /* bul:s3 */
 import StarButton from './StarButton.vue';
 
 const props = defineProps<{
@@ -111,21 +113,16 @@ function cancelPress() {
   pressTarget = null;
 }
 
-function iconFor(n: FileNode): string {
+// Special rows keep their emoji (trash/storage are not file-TYPE icons);
+// everything else renders the SVG icon set from lib/fileIcons.
+function specialEmojiFor(n: FileNode): string | null {
   if (n.basename === '.trash') return '🗑';
   if (n.mime_type === 'inode/storage') return '💾';
-  if (n.type === 'dir') return '📁';
-  const e = (n.extension || '').toLowerCase();
-  if (['jpg', 'jpeg', 'png', 'webp', 'gif', 'bmp', 'avif', 'heic', 'svg'].includes(e)) return '🖼';
-  if (['mp4', 'webm', 'mov', 'mkv', 'avi', 'ogv', 'm4v'].includes(e)) return '🎞';
-  if (['mp3', 'wav', 'flac', 'ogg', 'm4a', 'aac', 'opus'].includes(e)) return '🎵';
-  if (e === 'pdf') return '📕';
-  if (['doc', 'docx', 'odt', 'rtf'].includes(e)) return '📄';
-  if (['xls', 'xlsx', 'ods', 'csv'].includes(e)) return '📊';
-  if (['ppt', 'pptx', 'odp'].includes(e)) return '📽';
-  if (['zip', 'tar', 'gz', 'bz2', '7z', 'rar'].includes(e)) return '🗜';
-  if (['txt', 'md', 'log', 'json', 'yml', 'yaml', 'xml'].includes(e)) return '📝';
-  return '📎';
+  return null;
+}
+
+function isPinnedSpecial(n: FileNode): boolean {
+  return n.basename === '.trash' || n.mime_type === 'inode/storage';
 }
 
 function displayDate(ms: number | undefined): string {
@@ -141,20 +138,187 @@ function parentDir(path: string): string {
   return stripped.slice(0, idx);
 }
 
-const rows = computed(() => props.files);
+/* bul:s3 — search-result enrichment. The v0.2 backend inlines `snippet`
+ * (plain text, «» highlights) + `matched` on search hits; regular listings
+ * never carry them, so presence-gating keeps normal rows untouched and an
+ * older backend simply renders nothing extra. */
+function rowSnippet(n: FileNode): string {
+  const s = (n as Record<string, unknown>).snippet;
+  return typeof s === 'string' ? s : '';
+}
+
+function rowInContent(n: FileNode): boolean {
+  return matchedInContent((n as Record<string, unknown>).matched);
+}
+
+// ------------------------------------------------------------------
+// Column sorting — local to the list view. Default (null) keeps the
+// backend order, i.e. exactly the pre-existing behavior.
+// ------------------------------------------------------------------
+
+type SortKey = 'name' | 'size' | 'modified';
+const SORT_LS_KEY = 'filex.list-sort';
+
+const sortKey = ref<SortKey | null>(null);
+const sortDir = ref<'asc' | 'desc'>('asc');
+try {
+  const raw = localStorage.getItem(SORT_LS_KEY);
+  if (raw) {
+    const p = JSON.parse(raw) as { key?: unknown; dir?: unknown };
+    if (p.key === 'name' || p.key === 'size' || p.key === 'modified') sortKey.value = p.key;
+    if (p.dir === 'asc' || p.dir === 'desc') sortDir.value = p.dir;
+  }
+} catch {
+  /* private mode / bad JSON */
+}
+
+// Dates default to newest-first, the others to ascending.
+function defaultDir(key: SortKey): 'asc' | 'desc' {
+  return key === 'modified' ? 'desc' : 'asc';
+}
+
+// Click cycle per column: default direction → flipped → back to backend order.
+function toggleSort(key: SortKey) {
+  if (sortKey.value !== key) {
+    sortKey.value = key;
+    sortDir.value = defaultDir(key);
+  } else if (sortDir.value === defaultDir(key)) {
+    sortDir.value = sortDir.value === 'asc' ? 'desc' : 'asc';
+  } else {
+    sortKey.value = null;
+  }
+  try {
+    localStorage.setItem(
+      SORT_LS_KEY,
+      JSON.stringify({ key: sortKey.value, dir: sortDir.value }),
+    );
+  } catch {
+    /* quota */
+  }
+}
+
+function ariaSort(key: SortKey): 'ascending' | 'descending' | 'none' {
+  if (sortKey.value !== key) return 'none';
+  return sortDir.value === 'asc' ? 'ascending' : 'descending';
+}
+
+function modifiedMs(n: FileNode): number | null {
+  const v = n.last_modified;
+  if (!v) return null;
+  return v * (v < 1e12 ? 1000 : 1);
+}
+
+const rows = computed(() => {
+  const key = sortKey.value;
+  if (!key) return props.files;
+  // Virtual rows (.trash / storage drives) stay pinned on top in their
+  // original order; only real entries take part in the sort.
+  const pinned: FileNode[] = [];
+  const rest: FileNode[] = [];
+  for (const n of props.files) (isPinnedSpecial(n) ? pinned : rest).push(n);
+  const dir = sortDir.value === 'asc' ? 1 : -1;
+  rest.sort((a, b) => {
+    if (key === 'name') {
+      return (
+        dir *
+        a.basename.localeCompare(b.basename, undefined, { numeric: true, sensitivity: 'base' })
+      );
+    }
+    if (key === 'size') return dir * ((a.size ?? -1) - (b.size ?? -1));
+    const am = modifiedMs(a);
+    const bm = modifiedMs(b);
+    // Undated rows go last in both directions so date groups stay clean.
+    if (am == null && bm == null) return 0;
+    if (am == null) return 1;
+    if (bm == null) return -1;
+    return dir * (am - bm);
+  });
+  return [...pinned, ...rest];
+});
+
+// ------------------------------------------------------------------
+// Date grouping — only while sorted by modified date. Rows are split
+// into contiguous segments so the row markup below stays untouched.
+// ------------------------------------------------------------------
+
+interface Segment {
+  id: string;
+  /** null = no header (ungrouped mode, or the pinned virtual rows). */
+  label: string | null;
+  nodes: FileNode[];
+}
+
+const monthFmt = computed(
+  () =>
+    new Intl.DateTimeFormat(props.locale === 'tr' ? 'tr-TR' : 'en-US', {
+      month: 'long',
+      year: 'numeric',
+    }),
+);
+
+function bucketFor(ms: number | null): { id: string; label: string } {
+  if (ms == null) return { id: 'none', label: t('group.no_date') };
+  const d = new Date(ms);
+  const now = new Date();
+  const dayStart = (x: Date) => new Date(x.getFullYear(), x.getMonth(), x.getDate()).getTime();
+  const today = dayStart(now);
+  const day = dayStart(d);
+  const DAY = 86_400_000;
+  // Future stamps (clock skew) read best as "today".
+  if (day >= today) return { id: 'today', label: t('group.today') };
+  if (day === today - DAY) return { id: 'yesterday', label: t('group.yesterday') };
+  if (day > today - 7 * DAY) return { id: 'week', label: t('group.this_week') };
+  if (d.getFullYear() === now.getFullYear() && d.getMonth() === now.getMonth()) {
+    return { id: 'month', label: t('group.this_month') };
+  }
+  return { id: `m-${d.getFullYear()}-${d.getMonth()}`, label: monthFmt.value.format(d) };
+}
+
+const segments = computed<Segment[]>(() => {
+  const list = rows.value;
+  if (sortKey.value !== 'modified') return [{ id: 'all', label: null, nodes: list }];
+  const out: Segment[] = [];
+  let cur: Segment | null = null;
+  for (const n of list) {
+    const b = isPinnedSpecial(n) ? { id: 'pinned', label: null } : bucketFor(modifiedMs(n));
+    if (!cur || cur.id !== b.id) {
+      cur = { id: b.id, label: b.label, nodes: [] };
+      out.push(cur);
+    }
+    cur.nodes.push(n);
+  }
+  return out;
+});
 </script>
 
 <template>
   <div class="fe-list" :class="{ 'is-loading': loading, 'has-star-col': !!apiBase || apiBase === '' }">
     <div class="fe-list__head" role="row">
       <div class="fe-list__col fe-list__col--star" role="columnheader" aria-label="Star"></div>
-      <div class="fe-list__col fe-list__col--name" role="columnheader">{{ t('col.name') }}</div>
-      <div class="fe-list__col fe-list__col--size" role="columnheader">{{ t('col.size') }}</div>
-      <div class="fe-list__col fe-list__col--mod" role="columnheader">{{ t('col.modified') }}</div>
+      <div class="fe-list__col fe-list__col--name" role="columnheader" :aria-sort="ariaSort('name')">
+        <button type="button" class="fe-list__sort" :title="t('col.sort')" @click="toggleSort('name')">
+          {{ t('col.name') }}
+          <span v-if="sortKey === 'name'" class="fe-list__sort-arrow" aria-hidden="true">{{ sortDir === 'asc' ? '↑' : '↓' }}</span>
+        </button>
+      </div>
+      <div class="fe-list__col fe-list__col--size" role="columnheader" :aria-sort="ariaSort('size')">
+        <button type="button" class="fe-list__sort" :title="t('col.sort')" @click="toggleSort('size')">
+          {{ t('col.size') }}
+          <span v-if="sortKey === 'size'" class="fe-list__sort-arrow" aria-hidden="true">{{ sortDir === 'asc' ? '↑' : '↓' }}</span>
+        </button>
+      </div>
+      <div class="fe-list__col fe-list__col--mod" role="columnheader" :aria-sort="ariaSort('modified')">
+        <button type="button" class="fe-list__sort" :title="t('col.sort')" @click="toggleSort('modified')">
+          {{ t('col.modified') }}
+          <span v-if="sortKey === 'modified'" class="fe-list__sort-arrow" aria-hidden="true">{{ sortDir === 'asc' ? '↑' : '↓' }}</span>
+        </button>
+      </div>
     </div>
     <div class="fe-list__body" role="rowgroup">
+      <template v-for="seg in segments" :key="seg.id">
+      <div v-if="seg.label" class="fe-list__group" role="presentation">{{ seg.label }}</div>
       <div
-        v-for="n in rows"
+        v-for="n in seg.nodes"
         :key="n.path"
         class="fe-list__row"
         :class="{
@@ -188,14 +352,27 @@ const rows = computed(() => props.files);
           />
         </div>
         <div class="fe-list__col fe-list__col--name">
-          <span class="fe-list__icon" aria-hidden="true">{{ iconFor(n) }}</span>
+          <span v-if="specialEmojiFor(n)" class="fe-list__icon" aria-hidden="true">{{ specialEmojiFor(n) }}</span>
+          <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
+          <span v-else class="fe-list__icon fe-list__icon--svg" aria-hidden="true" v-html="fileIconSvg(n)"></span>
           <div class="fe-list__name-wrap">
-            <span class="fe-list__name" :title="n.basename">{{ nodeDisplayName(n) }}</span>
+            <span class="fe-list__name" :title="n.basename">
+              {{ nodeDisplayName(n) }}
+              <!-- bul:s3 — content-match badge -->
+              <span v-if="rowInContent(n)" class="fe-list__badge">{{ t('search.in_content') }}</span>
+            </span>
             <span
               v-if="showParentPath"
               class="fe-list__parent"
               :title="parentDir(n.path)"
             >{{ parentDir(n.path) || '—' }}</span>
+            <!-- bul:s3 — content snippet («» → <mark> via TEXT segments, no innerHTML) -->
+            <span v-if="rowSnippet(n)" class="fe-list__snippet">
+              <template v-for="(seg, si) in snippetSegments(rowSnippet(n))" :key="si">
+                <mark v-if="seg.match" class="fe-list__mark">{{ seg.text }}</mark>
+                <template v-else>{{ seg.text }}</template>
+              </template>
+            </span>
           </div>
         </div>
         <div class="fe-list__col fe-list__col--size">
@@ -205,6 +382,7 @@ const rows = computed(() => props.files);
           {{ displayDate(n.last_modified) }}
         </div>
       </div>
+      </template>
       <div v-if="!loading && rows.length === 0" class="fe-list__empty">
         {{ t('empty.folder') }}
       </div>

package/src/components/ShortcutsHelp.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+/**
+ * ShortcutsHelp — "?" cheat-sheet modal.
+ *
+ * Renders the SHORTCUTS table exported by useKeyboardShortcuts (single
+ * source of truth) grouped by section. Modal.vue supplies Esc handling,
+ * backdrop, focus and the close button.
+ */
+import { computed } from 'vue';
+import type { LocaleCode } from '../types/ExplorerConfig';
+import { useLocale } from '../composables/useLocale';
+import { SHORTCUTS, type ShortcutDef } from '../composables/useKeyboardShortcuts';
+import Modal from '../modals/Modal.vue';
+
+const props = defineProps<{
+  open: boolean;
+  locale: LocaleCode;
+}>();
+
+const emit = defineEmits<{
+  (e: 'close'): void;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+const groups = computed(() => {
+  const order: string[] = [];
+  const map = new Map<string, ShortcutDef[]>();
+  for (const s of SHORTCUTS) {
+    if (!map.has(s.groupKey)) {
+      map.set(s.groupKey, []);
+      order.push(s.groupKey);
+    }
+    map.get(s.groupKey)!.push(s);
+  }
+  return order.map((key) => ({ key, items: map.get(key)! }));
+});
+</script>
+
+<template>
+  <Modal :open="open" :title="t('shortcuts.title')" size="md" @close="emit('close')">
+    <div class="fe-shortcuts">
+      <section v-for="g in groups" :key="g.key" class="fe-shortcuts__group">
+        <h3 class="fe-shortcuts__heading">{{ t(g.key) }}</h3>
+        <div class="fe-shortcuts__table">
+          <div v-for="s in g.items" :key="s.labelKey" class="fe-shortcuts__row">
+            <span class="fe-shortcuts__keys">
+              <template v-for="(combo, i) in s.keys" :key="combo">
+                <kbd class="fe-kbd">{{ combo }}</kbd>
+                <span v-if="i < s.keys.length - 1" class="fe-shortcuts__or" aria-hidden="true">/</span>
+              </template>
+            </span>
+            <span class="fe-shortcuts__desc">{{ t(s.labelKey) }}</span>
+          </div>
+        </div>
+      </section>
+    </div>
+  </Modal>
+</template>

package/src/components/Toolbar.vue

@@ -11,7 +11,7 @@
  * Presentational only — all logic (rename, share, …) lives in
  * FileExplorer.vue, which listens for `action` emits.
  */
-import { computed, ref, watch } from 'vue';
+import { computed, onMounted, ref, watch } from 'vue';
 import type { ViewMode } from '../types/FileNode';
 import type { LocaleCode } from '../types/ExplorerConfig';
 import type { ContextAction } from './ContextMenu.vue';
@@ -69,8 +69,34 @@ const emit = defineEmits<{
   (e: 'go-up'): void;
   (e: 'action', key: string): void;
   (e: 'open-recents'): void;
+  (e: 'update:density', v: Density): void;
 }>();
 
+// Density toggle — the toolbar owns the persisted preference; the parent
+// only mirrors the value into a root class so both views pick it up.
+export type Density = 'comfortable' | 'compact';
+const DENSITY_LS_KEY = 'filex.density';
+const density = ref<Density>(
+  (() => {
+    try {
+      return localStorage.getItem(DENSITY_LS_KEY) === 'compact' ? 'compact' : 'comfortable';
+    } catch {
+      return 'comfortable';
+    }
+  })(),
+);
+onMounted(() => emit('update:density', density.value));
+
+function toggleDensity() {
+  density.value = density.value === 'compact' ? 'comfortable' : 'compact';
+  try {
+    localStorage.setItem(DENSITY_LS_KEY, density.value);
+  } catch {
+    /* quota */
+  }
+  emit('update:density', density.value);
+}
+
 const { t } = useLocale(() => props.locale);
 
 const searchEl = ref<HTMLInputElement | null>(null);
@@ -192,6 +218,44 @@ function fire(key: string) {
       </button>
     </div>
 
+    <button
+      type="button"
+      class="fe-btn fe-btn--icon-only fe-toolbar__density"
+      :class="{ 'is-active': density === 'compact' }"
+      :aria-pressed="density === 'compact'"
+      :aria-label="density === 'compact' ? t('toolbar.density.comfortable') : t('toolbar.density.compact')"
+      :title="density === 'compact' ? t('toolbar.density.comfortable') : t('toolbar.density.compact')"
+      @click="toggleDensity"
+    >
+      <!-- Row-spacing glyph: tight rows when compact is ON, airy rows otherwise. -->
+      <svg
+        v-if="density === 'compact'"
+        class="fe-ficon"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.8"
+        stroke-linecap="round"
+        aria-hidden="true"
+        focusable="false"
+      >
+        <path d="M4 6.5h16M4 10.5h16M4 14.5h16M4 18.5h16" />
+      </svg>
+      <svg
+        v-else
+        class="fe-ficon"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.8"
+        stroke-linecap="round"
+        aria-hidden="true"
+        focusable="false"
+      >
+        <path d="M4 5.5h16M4 12h16M4 18.5h16" />
+      </svg>
+    </button>
+
     <div class="fe-toolbar__view" role="tablist" aria-label="View">
       <button
         type="button"

package/src/composables/useFileApi.ts

@@ -101,6 +101,34 @@ export interface InviteResponse {
   emailed: boolean;
 }
 
+/* === bul:s3 — global search (GET /api/files/search) === */
+
+export type GlobalSearchScope = 'name' | 'content' | 'all';
+
+/**
+ * One hit from the dedicated files-search endpoint. The backend returns raw
+ * node rows (`{results: [...]}`), so `path` is the IN-STORAGE relative path
+ * (no `adapter://` prefix) and the storage comes back as a numeric
+ * `storage_id`. `snippet`/`matched` are the v0.2 "Bul" contract additions —
+ * older backends simply omit them, so every consumer must stay
+ * undefined-safe.
+ */
+export interface GlobalSearchHit {
+  id?: number;
+  storage_id?: number;
+  name?: string;
+  path?: string;
+  /** `file` | `dir` (backend NodeType). */
+  type?: string;
+  size?: number;
+  mime?: string;
+  /** Plain-text content snippet; matches wrapped in «» (never HTML). */
+  snippet?: string;
+  /** Where the hit matched: name | content | both. */
+  matched?: 'name' | 'content' | 'both';
+  [k: string]: unknown;
+}
+
 /**
  * Resolve a Vuefinder-compatible endpoint map from the user's config.
  * Either `apiBase` is set (auto-derive everything) or each route is
@@ -340,6 +368,22 @@ export function useFileApi(config: ExplorerConfig) {
     return jsonFetch<ManagerResponse>(managerUrl('search', { path, filter }));
   }
 
+  /* === bul:s3 — global "search everywhere" ===
+   * Derived from the manager endpoint by swapping `/manager` for `/search`
+   * (same trick permissionsUrl uses), so embedded proxies that forward the
+   * whole /api/files/* subtree keep working. Errors and legacy backends
+   * degrade to an empty result list — the palette just shows nothing. */
+  async function globalSearch(
+    query: string,
+    opts: { limit?: number; scope?: GlobalSearchScope } = {},
+  ): Promise<GlobalSearchHit[]> {
+    const base = endpoints.manager.replace(/\/manager(\?.*)?$/, '/search');
+    const sep = base.includes('?') ? '&' : '?';
+    const url = `${base}${sep}${qs({ q: query, limit: opts.limit, scope: opts.scope })}`;
+    const data = await jsonFetch<{ results?: GlobalSearchHit[] | null }>(url);
+    return Array.isArray(data?.results) ? data.results : [];
+  }
+
   async function subfolders(path: string): Promise<{ folders: FileNode[] }> {
     return jsonFetch<{ folders: FileNode[] }>(managerUrl('subfolders', { path }));
   }
@@ -661,6 +705,7 @@ export function useFileApi(config: ExplorerConfig) {
     // Manager
     index,
     search,
+    globalSearch /* bul:s3 */,
     subfolders,
     newFolder,
     rename,

package/src/composables/useKeyboardShortcuts.ts

@@ -21,9 +21,41 @@ export interface ShortcutHandlers {
   onDuplicate?: () => void; // Ctrl+D
   onPathJump?: () => void; // Cmd+K / Ctrl+K
   onGoUp?: () => void; // Alt+Up / Backspace (when nothing selected)
+  onShowHelp?: () => void; // ? (Shift+/ on most layouts)
   hasSelection?: () => boolean; // disambiguates Backspace
 }
 
+/**
+ * SHORTCUTS — the single source of truth for the shortcut cheat-sheet
+ * (ShortcutsHelp.vue). Only shortcuts actually wired by FileExplorer are
+ * listed; labels/groups resolve through the locale catalogue so the help
+ * dialog stays tr/en aware. `keys` entries are display combos — each one
+ * renders as its own <kbd>, alternatives joined visually with "/".
+ */
+export interface ShortcutDef {
+  keys: string[];
+  labelKey: string;
+  groupKey: string;
+}
+
+export const SHORTCUTS: ShortcutDef[] = [
+  // Navigation
+  { keys: ['Ctrl+K'], labelKey: 'shortcuts.palette', groupKey: 'shortcuts.group.nav' },
+  { keys: ['/'], labelKey: 'shortcuts.search', groupKey: 'shortcuts.group.nav' },
+  { keys: ['Alt+↑', 'Backspace'], labelKey: 'shortcuts.go_up', groupKey: 'shortcuts.group.nav' },
+  { keys: ['Enter'], labelKey: 'shortcuts.open', groupKey: 'shortcuts.group.nav' },
+  { keys: ['Esc'], labelKey: 'shortcuts.close', groupKey: 'shortcuts.group.nav' },
+  { keys: ['?'], labelKey: 'shortcuts.help', groupKey: 'shortcuts.group.nav' },
+  // Selection
+  { keys: ['Ctrl+A'], labelKey: 'shortcuts.select_all', groupKey: 'shortcuts.group.selection' },
+  // File operations
+  { keys: ['F2'], labelKey: 'shortcuts.rename', groupKey: 'shortcuts.group.file' },
+  { keys: ['Del'], labelKey: 'shortcuts.delete', groupKey: 'shortcuts.group.file' },
+  { keys: ['Ctrl+X'], labelKey: 'shortcuts.cut', groupKey: 'shortcuts.group.file' },
+  { keys: ['Ctrl+C'], labelKey: 'shortcuts.copy', groupKey: 'shortcuts.group.file' },
+  { keys: ['Ctrl+V'], labelKey: 'shortcuts.paste', groupKey: 'shortcuts.group.file' },
+];
+
 export function useKeyboardShortcuts(rootEl: Ref<HTMLElement | null>, handlers: ShortcutHandlers) {
   function onKey(e: KeyboardEvent) {
     const root = rootEl.value;
@@ -87,6 +119,12 @@ export function useKeyboardShortcuts(rootEl: Ref<HTMLElement | null>, handlers:
           handlers.onFocusSearch();
         }
         break;
+      case '?':
+        if (handlers.onShowHelp && !ctrl && !e.altKey) {
+          e.preventDefault();
+          handlers.onShowHelp();
+        }
+        break;
       case 'a':
       case 'A':
         if (ctrl && handlers.onSelectAll) {

package/src/composables/useRealtime.ts

@@ -19,6 +19,12 @@ export interface RealtimeApi {
 export function useRealtime(api: RealtimeApi, opts: { reload: () => void }) {
   const presenceUsers: Ref<PresenceUser[]> = ref([]);
   const connected = ref(false);
+  // True while the live socket is unavailable and the polling fallback is
+  // active — the explorer surfaces a small "no live connection" badge from it.
+  // Stays false during ordinary reconnect attempts, so brief blips don't flash
+  // the badge; only a genuinely given-up socket (RealtimeClient onFallback)
+  // flips it.
+  const degraded = ref(false);
 
   let client: RealtimeClient | null = null;
   let pendingSubscribe: string | null = null;
@@ -42,6 +48,7 @@ export function useRealtime(api: RealtimeApi, opts: { reload: () => void }) {
   }
 
   function onFallback(active: boolean): void {
+    degraded.value = active;
     if (active) {
       // No live socket → poll the listing; presence isn't available here.
       presenceUsers.value = [];
@@ -88,7 +95,8 @@ export function useRealtime(api: RealtimeApi, opts: { reload: () => void }) {
     }
     client?.close();
     client = null;
+    degraded.value = false;
   }
 
-  return { presenceUsers, connected, start, subscribe, setFocus, stop };
+  return { presenceUsers, connected, degraded, start, subscribe, setFocus, stop };
 }

package/src/index.ts

@@ -57,6 +57,10 @@ export { isExternalUsable } from './types/FileNode';
 // ——— Composables (consumers can roll their own UI on top) ———
 export { useFileApi, resolveEndpoints } from './composables/useFileApi';
 export type { FileApi, ManagerResponse, PendingOpDto } from './composables/useFileApi';
+/* bul:s3 — global-search contract types + snippet helpers */
+export type { GlobalSearchHit, GlobalSearchScope } from './composables/useFileApi';
+export { snippetSegments, matchedInContent } from './lib/snippet';
+export type { SnippetSegment, SearchMatched } from './lib/snippet';
 
 export { useUploadChunked } from './composables/useUploadChunked';
 export type { UploadJob, UploadOptions } from './composables/useUploadChunked';