@brftech/filex-core 0.43.0 → 0.43.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brftech/filex-core",
-  "version": "0.43.0",
+  "version": "0.43.2",
   "description": "filex core — Vue 3 source of truth for the filex file manager (FileExplorer + ConnectionsPanel SFCs, composables, types)",
   "type": "module",
   "main": "./dist/filex-core.umd.cjs",

package/src/components/GalleryView.vue

@@ -25,6 +25,7 @@ import {
   type FilePreview,
 } from '../lib/filePreview'; /* gorunum:v1-preview */
 import StarButton from './StarButton.vue';
+import ThumbTile from './ThumbTile.vue';
 import { applyDragGhost } from '../lib/dragGhost';
 import { parentDirOf } from '../lib/listing'; /* the folder a row sits in — one split rule for every view */
 import {
@@ -358,41 +359,34 @@ function metaFor(n: FileNode): string {
             v-html="fileIconTile(n)"
           ></span>
         </template>
-        <!-- draggable="false" for the same reason as GridView: HTML5 image
-             drag adds a 'Files' MIME to dataTransfer, which would trip the
-             parent's upload handler on internal drags. -->
-        <img
-          v-else-if="thumbOf(n)"
-          :src="thumbOf(n)!"
+        <!-- ⚠⚠ Through ThumbTile, as in GridView: read in this template, each
+             thumbnail that arrived re-rendered every tile of the folder. The
+             tile draws the <img> (draggable="false", same reason as GridView)
+             and the play badge over a video frame; its slot until then. -->
+        <ThumbTile
+          v-else
+          :node="n"
+          :src-of="thumbOf"
+          :video-badge="drawsAsVideo(n)"
           :alt="n.basename"
           :class="{ 'fe-thumb--page': drawsAsPage(n) /* gorunum:v1-preview — crop a page from its TOP */ }"
-          loading="lazy"
-          draggable="false"
-        />
-        <!-- ikon:emoji — see GridView: the folder shape survives, the padlock
-             is cut out of it, and the name the 🔒 never had is on the span. -->
-        <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
-        <span
-          v-else-if="isEncryptedFolder(n)"
-          class="fe-gal__icon fe-gal__icon--svg"
-          role="img"
-          :aria-label="t('e2e.badge')"
-          v-html="encryptedFolderTile()"
-        ></span>
-        <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
-        <span v-else class="fe-gal__icon fe-gal__icon--svg" v-html="fileIconTile(n)"></span>
+        >
+          <!-- ikon:emoji — see GridView: the folder shape survives, the padlock
+               is cut out of it, and the name the 🔒 never had is on the span. -->
+          <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
+          <span
+            v-if="isEncryptedFolder(n)"
+            class="fe-gal__icon fe-gal__icon--svg"
+            role="img"
+            :aria-label="t('e2e.badge')"
+            v-html="encryptedFolderTile()"
+          ></span>
+          <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
+          <span v-else class="fe-gal__icon fe-gal__icon--svg" v-html="fileIconTile(n)"></span>
+        </ThumbTile>
         <!-- Same star chip as the grid, same component, same rule: painted
              when starred, on hover/focus otherwise. It sits above .fe-gal__meta
              (which is aria-hidden and covers the tile's foot on hover). -->
-        <!-- gorunum:v1-preview — a frame lifted out of a video is, on a card,
-             indistinguishable from a photograph. The badge is the difference,
-             and it is drawn only over a real frame: a video that fell back to
-             its type tile already says what it is. -->
-        <span
-          v-if="!previewKind(n) && thumbOf(n) && drawsAsVideo(n)"
-          class="fe-thumb__play"
-          aria-hidden="true"
-        ></span>
         <!-- issue #26 — the card's checkbox, the one click that selects: the
              corner opposite the star, on the same reveal rule plus "anything
              is selected" (styles/base.css .fe-item-check). -->

package/src/components/GridView.vue

@@ -38,6 +38,7 @@ import {
 } from '../lib/dateGroups'; /* gruplama */
 import { useSortStore, type ListingOrder } from '../lib/sortOrder'; /* gruplama */
 import StarButton from './StarButton.vue';
+import ThumbTile from './ThumbTile.vue';
 import { snippetSegments } from '../lib/snippet'; /* bul:s3 */
 import { applyDragGhost } from '../lib/dragGhost'; /* wiring:c4 */
 import { contentDir } from '../lib/direction';
@@ -229,7 +230,8 @@ function headingBefore(n: FileNode): string | null {
 
 
 // Prefer the authenticated resolver when the host wired one; otherwise fall
-// back to the raw URL (legacy same-origin behavior).
+// back to the raw URL (legacy same-origin behavior). ⚠ Called by ThumbTile,
+// not by this template — see the note on the tile in the markup.
 function thumbOf(n: FileNode): string | null {
   return props.thumbSrc ? props.thumbSrc(n) : (n.thumb_url ?? null);
 }
@@ -512,48 +514,43 @@ function snippetTitle(snippet: string): string {
             v-html="fileIconTile(n)"
           ></span>
         </template>
-        <!--
-          draggable="false" — HTML5 image drag dataTransfer adds 'Files'
-          MIME, which trips the parent's upload handler; without this
-          the user dragging an item with a thumbnail re-uploads it.
-          Parent card stays draggable=true so internal move works.
-        -->
-        <img
-          v-else-if="thumbOf(n)"
-          :src="thumbOf(n)!"
+        <!-- ⚠⚠ The thumbnail is read inside ThumbTile, never here: read in
+             this template, each thumbnail that arrived re-rendered every card
+             of the folder (see ThumbTile). The tile draws the <img> once there
+             is a picture — draggable="false", because an image drag puts a
+             'Files' MIME on the dataTransfer and the parent's upload handler
+             re-uploads the file being moved — and its slot until then.
+             gorunum:v1-preview — the play badge goes over a real video frame
+             only: a video that fell back to its type tile already says what
+             it is. -->
+        <ThumbTile
+          v-else
+          :node="n"
+          :src-of="thumbOf"
+          :video-badge="drawsAsVideo(n)"
           :alt="n.basename"
           :class="{ 'fe-thumb--page': drawsAsPage(n) /* gorunum:v1-preview — crop a page from its TOP */ }"
-          loading="lazy"
-          draggable="false"
-        />
-        <!-- ikon:emoji — an encrypted folder is still a FOLDER, so it keeps the
-             folder's own shape and colour with the padlock cut out of it; the
-             🔒 it replaces said "locked" and nothing else. One definition,
-             in lib/fileIcons, for all three views. -->
-        <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
-        <span
-          v-else-if="isEncryptedFolder(n)"
-          class="fe-grid__icon fe-grid__icon--svg"
-          role="img"
-          :aria-label="t('e2e.badge')"
-          v-html="encryptedFolderTile()"
-        ></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="fileIconTile(n)"></span>
+        >
+          <!-- ikon:emoji — an encrypted folder is still a FOLDER, so it keeps the
+               folder's own shape and colour with the padlock cut out of it; the
+               🔒 it replaces said "locked" and nothing else. One definition,
+               in lib/fileIcons, for all three views. -->
+          <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
+          <span
+            v-if="isEncryptedFolder(n)"
+            class="fe-grid__icon fe-grid__icon--svg"
+            role="img"
+            :aria-label="t('e2e.badge')"
+            v-html="encryptedFolderTile()"
+          ></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="fileIconTile(n)"></span>
+        </ThumbTile>
         <!-- Star, ON the tile. A hover-only affordance would be invisible to
              the person looking for what they starred, so the chip is always
              painted once the file IS starred and only appears on hover/focus
              otherwise (see .fe-grid__star in styles/base.css). @click.stop so
              starring never doubles as opening the card. -->
-        <!-- gorunum:v1-preview — a frame lifted out of a video is, on a card,
-             indistinguishable from a photograph. The badge is the difference,
-             and it is drawn only over a real frame: a video that fell back to
-             its type tile already says what it is. -->
-        <span
-          v-if="!previewKind(n) && thumbOf(n) && drawsAsVideo(n)"
-          class="fe-thumb__play"
-          aria-hidden="true"
-        ></span>
         <div v-if="canStar(n)" class="fe-grid__star" @click.stop @dblclick.stop>
           <StarButton
             :starred="!!starredIds?.has(n.id!)"

package/src/components/ListView.vue

@@ -65,6 +65,7 @@ import {
 } from '../lib/viewPrefs'; /* tablo:t1 — per-folder columns */
 import DataTable, { type DataColumn } from './DataTable.vue';
 import StarButton from './StarButton.vue';
+import ThumbTile from './ThumbTile.vue';
 
 const props = defineProps<{
   files: FileNode[];
@@ -786,21 +787,24 @@ const tableGroups = computed(() =>
         v-html="encryptedFolderTile()"
       ></span>
       <!-- tablo:t1 — the real thumbnail, at the tile's own size so the row
-           height does not move. `draggable="false"`: dragging an <img> puts a
-           'Files' MIME on the dataTransfer and the parent's upload handler
-           re-uploads the thing you were only moving. -->
-      <img
-        v-else-if="thumbOf(row)"
+           height does not move. ⚠⚠ Through ThumbTile, never read in this
+           template: here, each thumbnail that arrived re-rendered every row of
+           the table. The tile draws the <img> (`draggable="false"`: dragging
+           an <img> puts a 'Files' MIME on the dataTransfer and the parent's
+           upload handler re-uploads the thing you were only moving) and the
+           type tile until then. -->
+      <ThumbTile
+        v-else
+        :node="row"
+        :src-of="thumbOf"
         class="fe-list__icon fe-list__icon--img"
         :class="{ 'fe-thumb--page': drawsAsPage(row) }"
-        :src="thumbOf(row)!"
         alt=""
         aria-hidden="true"
-        loading="lazy"
-        draggable="false"
-      />
-      <!-- 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="fileIconTile(row)"></span>
+      >
+        <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
+        <span class="fe-list__icon fe-list__icon--svg" aria-hidden="true" v-html="fileIconTile(row)"></span>
+      </ThumbTile>
       <div class="fe-list__name-wrap">
         <span class="fe-list__name" :title="nameTitle(row)">
           <!-- ⚠ RTL: `<bdi>` — the name is the person's text, not the

package/src/components/ThumbTile.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+/**
+ * ThumbTile — one file's thumbnail, or whatever the view draws instead.
+ *
+ * ⚠⚠ Why a component. A thumbnail's object URL arrives later, and whatever
+ * read it is woken when it does. Read in a folder view's own template, that was
+ * the whole view: every arrival re-rendered every row (see useThumbs). Read
+ * here, it is this tile.
+ *
+ * It also asks late. The resolver starts the fetch, and it is only called once
+ * the tile is near the viewport (lib/nearViewport), so opening a folder no
+ * longer downloads the thumbnails of tiles nobody has scrolled to.
+ *
+ * The <img> takes the attributes the view gives the tile (class, alt, aria-*);
+ * the default slot is the fallback — the view's type tile — drawn until the
+ * picture is there, and for good when there is none.
+ *
+ * ⚠ No `loading="lazy"`: the picture is already only handed over near the
+ * viewport, and it is an object URL in memory, so lazy would defer nothing but
+ * the decode — and an <img> that has not loaded yet when useThumbs revokes its
+ * URL (its oldest, past the cache's cap) would come up broken.
+ */
+import { computed, getCurrentInstance, onBeforeUnmount, onMounted, ref } from 'vue';
+import type { FileNode } from '../types/FileNode';
+import { whenNearViewport } from '../lib/nearViewport';
+
+defineOptions({ inheritAttrs: false });
+
+const props = defineProps<{
+  node: FileNode;
+  /** The view's resolver: the object URL to draw, or null (not yet, or none). */
+  srcOf: (n: FileNode) => string | null;
+  /** Draw the play badge over the picture — a frame lifted out of a video is,
+   *  on a card, indistinguishable from a photograph. */
+  videoBadge?: boolean;
+}>();
+
+const near = ref(false);
+let stopWaiting: (() => void) | null = null;
+
+onMounted(() => {
+  /* The tile draws no box of its own (it is the picture, or the fallback), so
+     it watches the box it sits in — the view's thumbnail cell. */
+  const anchor = getCurrentInstance()?.subTree.el as Node | null | undefined;
+  stopWaiting = whenNearViewport(anchor?.parentElement, () => {
+    near.value = true;
+  });
+});
+onBeforeUnmount(() => stopWaiting?.());
+
+const src = computed(() => (near.value ? props.srcOf(props.node) : null));
+</script>
+
+<template>
+  <img v-if="src" v-bind="$attrs" :src="src" draggable="false" />
+  <slot v-else />
+  <span v-if="src && videoBadge" class="fe-thumb__play" aria-hidden="true"></span>
+</template>

package/src/composables/useThumbs.ts

@@ -1,4 +1,4 @@
-// useThumbs — authenticated thumbnail loader for the grid view.
+// useThumbs — authenticated thumbnail loader for the folder views.
 //
 // The backend emits `thumb_url` as a ROOT-RELATIVE path ("/api/files/thumb/{id}").
 // A plain `<img src>` only works for the native same-origin SPA: an embedded
@@ -6,9 +6,24 @@
 // and, even with the URL fixed, `<img>` cannot carry the bearer header a
 // proxied host (fishapp PWA) requires. So thumbs are fetched through the same
 // auth machinery as every API call (headers + credentials), cached as object
-// URLs, and handed to the grid; a failed fetch falls back to the file icon.
+// URLs, and handed to the views; a failed fetch falls back to the file icon.
+//
+// ⚠⚠ An arrival wakes ONE tile. The object URLs used to live in one reactive
+// record that was REPLACED as each thumbnail arrived, so every arrival woke
+// everything that had read any thumbnail — the whole folder view, which read
+// them all. Field report: a folder of 344 files (~240 thumbnails) re-rendered
+// itself ~240 times in a few seconds; a fast Mac lost ~4 s, a slower Windows PC
+// froze Edge for ~30 s and ran a Chrome tab out of memory. The cache is now a
+// reactive Map read per key, and the views read it through ThumbTile (one
+// component per tile), so an arrival re-renders the tile that shows it.
+//
+// ⚠ Keyed by picture, not by URL. `thumb_url` carries a signature whose expiry
+// moves every hour; keyed by URL, the first listing after the hour turned
+// fetched every thumbnail of the folder again. The key is the URL's path plus
+// the file's `last_modified`: a rotated signature is the same picture, an edited
+// file is not.
 
-import { ref } from 'vue';
+import { shallowReactive, toRaw } from 'vue';
 import type { FileNode } from '../types/FileNode';
 
 interface ThumbApiSlice {
@@ -20,10 +35,22 @@ interface ThumbApiSlice {
  *  small (~KBs) so this is generous while still bounding a long session. */
 const MAX_CACHED = 500;
 
+/** The cache key for a node's thumbnail — null when it has none. */
+function thumbKey(n: FileNode): string | null {
+  const raw = n.thumb_url;
+  if (!raw) return null;
+  const q = raw.indexOf('?');
+  return `${q === -1 ? raw : raw.slice(0, q)}|${n.last_modified ?? ''}`;
+}
+
 export function useThumbs(apiBase: string | undefined, api: ThumbApiSlice) {
-  const urls = ref<Record<string, string>>({});
+  const cache = shallowReactive(new Map<string, string>());
   const order: string[] = [];
+  /** Signed URLs that failed. Per URL, not per key: 404 (thumb evicted
+   *  server-side) or an auth hiccup is not retried within the session, but a
+   *  freshly signed URL for the same picture may be tried once. */
   const failed = new Set<string>();
+  /** Keys being fetched — one request per picture however many URLs name it. */
   const pending = new Set<string>();
 
   function resolveUrl(raw: string): string {
@@ -32,19 +59,21 @@ export function useThumbs(apiBase: string | undefined, api: ThumbApiSlice) {
     return base && raw.startsWith('/') ? base + raw : raw;
   }
 
-  /** Reactive: returns the loaded object URL for the node's thumb, kicking off
-   *  the fetch on first sight. null = not (yet) available → show the icon. */
+  /** Reactive, per node: returns the loaded object URL for the node's thumb,
+   *  kicking off the fetch on first sight. null = not (yet) available → show
+   *  the icon. Only what read THIS node's key is woken when it arrives. */
   function src(n: FileNode): string | null {
     const raw = n.thumb_url;
-    if (!raw) return null;
-    const got = urls.value[raw];
+    const key = thumbKey(n);
+    if (!raw || !key) return null;
+    const got = cache.get(key);
     if (got) return got;
-    if (!failed.has(raw) && !pending.has(raw)) void load(raw);
+    if (!failed.has(raw) && !pending.has(key)) void load(raw, key);
     return null;
   }
 
-  async function load(raw: string): Promise<void> {
-    pending.add(raw);
+  async function load(raw: string, key: string): Promise<void> {
+    pending.add(key);
     try {
       const res = await fetch(resolveUrl(raw), {
         headers: await api.authHeaders({ Accept: '*/*' }),
@@ -53,22 +82,25 @@ export function useThumbs(apiBase: string | undefined, api: ThumbApiSlice) {
       if (!res.ok) throw new Error(String(res.status));
       const blob = await res.blob();
       if (order.length >= MAX_CACHED) {
+        // ⚠ Dropped without a word to the tile still showing it: woken, the
+        // tile would fetch it again, and that arrival would drop the next
+        // oldest — past MAX_CACHED thumbnails on screen, a loop that never
+        // ends. Its <img> has long loaded, and a loaded image outlives its
+        // revoked URL; a tile drawn later asks again, once.
         const evict = order.shift();
-        if (evict && urls.value[evict]) {
-          URL.revokeObjectURL(urls.value[evict]);
-          const next = { ...urls.value };
-          delete next[evict];
-          urls.value = next;
+        const store = toRaw(cache);
+        const old = evict ? store.get(evict) : undefined;
+        if (evict && old) {
+          URL.revokeObjectURL(old);
+          store.delete(evict);
         }
       }
-      order.push(raw);
-      urls.value = { ...urls.value, [raw]: URL.createObjectURL(blob) };
+      order.push(key);
+      cache.set(key, URL.createObjectURL(blob));
     } catch {
-      // 404 (thumb evicted server-side) or auth hiccup — icon fallback, and we
-      // don't retry within this session to avoid hammering.
       failed.add(raw);
     } finally {
-      pending.delete(raw);
+      pending.delete(key);
     }
   }
 

package/src/lib/nearViewport.ts

@@ -0,0 +1,77 @@
+/**
+ * whenNearViewport — call `cb` once `el` comes within NEAR of the viewport.
+ *
+ * A folder view puts every tile on the page at once, and a thumbnail is a
+ * request: a folder of 344 files asked for ~240 of them the moment it opened,
+ * most for tiles nobody had scrolled to. ThumbTile asks only once this says
+ * its tile is close.
+ *
+ * ONE IntersectionObserver for the page, not one per tile, and each element is
+ * heard once and then forgotten. With a null root it watches the viewport, and
+ * a tile hidden by the scroll box it sits in (the explorer's pane scrolls on
+ * its own) does not count as near. Where IntersectionObserver does not exist
+ * (an old engine, a test DOM) every element counts as near at once — which is
+ * how every tile behaved before.
+ */
+
+/** How far outside the viewport a tile already counts as near: a thumbnail
+ *  should be on its way before the tile scrolls in, not after. */
+const NEAR = '300px';
+
+let io: IntersectionObserver | null = null;
+const waiting = new Map<Element, Set<() => void>>();
+
+function observer(): IntersectionObserver {
+  if (!io) {
+    io = new IntersectionObserver(
+      (entries) => {
+        for (const e of entries) {
+          if (!e.isIntersecting) continue;
+          const cbs = waiting.get(e.target);
+          if (!cbs) continue;
+          waiting.delete(e.target);
+          io?.unobserve(e.target);
+          cbs.forEach((cb) => cb());
+        }
+      },
+      // `rootMargin` widens the viewport only: a tile in the pane's own scroll
+      // box is still cut off at that box's edge. `scrollMargin` widens the
+      // scroll boxes too (Chromium 120+; an engine that does not know it
+      // ignores it, and the picture is asked for as the tile scrolls in).
+      { rootMargin: NEAR, scrollMargin: NEAR } as IntersectionObserverInit,
+    );
+  }
+  return io;
+}
+
+/** Call `cb` once `el` is near the viewport. Returns a function that cancels
+ *  the wait (call it when the element goes away first). */
+export function whenNearViewport(el: Element | null | undefined, cb: () => void): () => void {
+  if (!el || typeof IntersectionObserver === 'undefined') {
+    cb();
+    return () => {};
+  }
+  let cbs = waiting.get(el);
+  if (!cbs) {
+    cbs = new Set();
+    waiting.set(el, cbs);
+    observer().observe(el);
+  }
+  cbs.add(cb);
+  return () => {
+    const set = waiting.get(el);
+    if (!set) return;
+    set.delete(cb);
+    if (set.size === 0) {
+      waiting.delete(el);
+      io?.unobserve(el);
+    }
+  };
+}
+
+/** Tests only: drop the shared observer so the next wait builds a fresh one. */
+export function __resetNearViewport(): void {
+  io?.disconnect();
+  io = null;
+  waiting.clear();
+}