xtralab 0.15.0 → 0.15.1

package/src/fileBrowser/contents.ts

@@ -60,6 +60,9 @@ export function toServerPath(canonicalPath: string): string {
     : canonicalPath;
 }
 
+/**
+ * The immediate children of a directory, as canonical `@pierre/trees` paths.
+ */
 interface IListedDirectory {
   /**
    * Canonical paths for every immediate child of the requested directory.

package/src/fileBrowser/dragAndDrop.ts

@@ -14,7 +14,13 @@ import { ROOT_LOAD_KEY, canonicalBasename, parentOf } from './contents';
  * One tree-model move a drop performs, as canonical paths.
  */
 export interface IDropMove {
+  /**
+   * The canonical path of the dragged item.
+   */
   from: string;
+  /**
+   * The canonical destination path: its basename under the target directory.
+   */
   to: string;
 }
 
@@ -55,9 +61,6 @@ export function computeDropMoves(context: FileTreeDropContext): IDropMove[] {
     .map(path => ({ from: path, to: `${dir}${canonicalBasename(path)}` }));
 }
 
-/**
- * The drop target the tree reports for a move to the workspace root.
- */
 const ROOT_DROP_TARGET: FileTreeDropTarget = {
   directoryPath: null,
   flattenedSegmentPath: null,
@@ -92,8 +95,17 @@ export function createTreeDragAndDropConfig(
   };
 }
 
+/**
+ * Options for {@link useRootDropZone}.
+ */
 interface IRootDropZoneOptions {
+  /**
+   * The tree model, queried for the selection at drag start.
+   */
   model: FileTree;
+  /**
+   * The drop handler ref, filled by the contents-sync effect.
+   */
   handlerRef: React.RefObject<ITreeDropHandler | null>;
   /**
    * The light-DOM wrapper around the tree host; composed drag events
@@ -104,10 +116,8 @@ interface IRootDropZoneOptions {
 
 /**
  * Accept drops on the empty space below the last row as moves to the
- * workspace root — the tree resolves a drop target only while the
- * cursor is over a row and silently discards such drops. dragstart
- * records the dragged paths; a drop whose composed path contains no
- * row hands them over as a root move.
+ * workspace root — the tree resolves a drop target only while the cursor
+ * is over a row and silently discards such drops.
  */
 export function useRootDropZone(options: IRootDropZoneOptions): void {
   const { model, handlerRef, wrapperRef } = options;

package/src/fileBrowser/fileBrowser.tsx

@@ -36,69 +36,37 @@ import { loadGitStatusEntries } from './gitStatus';
 import { FILE_BROWSER_ICONS } from './icons';
 import type { XtralabFileBrowser } from './widget';
 
-/**
- * Load state for a directory in the file tree. Directories are tracked from
- * the moment they are first observed (as a child of a loaded parent) so the
- * subscribe/diff loop can decide whether to fetch their contents on expand.
- */
 type LoadState = 'unloaded' | 'loading' | 'loaded';
 
 /**
- * Polling cadence for the git status decoration. Out-of-band changes (a
- * terminal `git add`, a `git pull`, a file edited outside the JupyterLab
- * editor) become visible within this interval without a manual refresh.
- * Aligned with the git panel's own polling so both views update on the
- * same rhythm.
+ * Git status poll cadence, aligned with the git panel's polling so both
+ * views update on the same rhythm.
  */
 const GIT_STATUS_POLL_INTERVAL_MS = 5000;
 
-/**
- * Upper bound on the git status poll's exponential backoff. Matches the
- * other polls in the plugin so behavior is consistent across views.
- */
 const GIT_STATUS_POLL_MAX_MS = 300_000;
 
 /**
- * Auto-refresh cadence for the file listing itself. Matches the default
- * JupyterLab file browser (`DEFAULT_REFRESH_INTERVAL` in
- * `@jupyterlab/filebrowser`) so the tree picks up files created outside
- * JupyterLab (terminal commands, external editors, `git pull`, …) within
- * the same window as the stock browser.
+ * Listing auto-refresh cadence; matches the default file browser's
+ * `DEFAULT_REFRESH_INTERVAL` for picking up out-of-band file changes.
  */
 const FILE_LISTING_REFRESH_INTERVAL_MS = 10000;
 
-/**
- * Upper bound on the auto-refresh backoff when polls fail repeatedly.
- * Matches the default file browser's `max: 300 * 1000` — five minutes is
- * long enough that a server-side outage stops hammering the API, but
- * short enough that a transient failure heals on its own.
- */
 const FILE_LISTING_REFRESH_MAX_MS = 300_000;
 
 /**
- * Server-relative repository path used for `/git/*` calls. Empty string
- * means "use the JupyterLab server's root and let git resolve the
- * enclosing repo" — same convention as the git panel and the launcher
- * dashboard.
+ * Repo path for `/git/*` calls; empty means the server root, letting git
+ * resolve the enclosing repo (same convention as the git panel).
  */
 const GIT_REPO_PATH = '';
 
-/**
- * The custom-element tag used by `@pierre/trees` for its shadow host. Kept
- * as a constant rather than imported so we don't pay the `@pierre/trees`
- * resolution cost just for one string.
- */
 const FILE_TREE_TAG = 'file-tree-container';
 
 /**
- * Injected into the tree's shadow root. The second rule hides the search
- * box unless the host carries the visibility marker set by the filter
- * bridge effect below — `@pierre/trees` always renders the box when
- * `search` is enabled, and its stylesheet lives in the shadow root where
- * outside CSS cannot reach. The third rule restyles the drag-hover row:
- * the library paints it with the selection background, which xtralab
- * maps to a full-strength brand color that is illegible without the
- * inverted selection foreground — hence the quieter ring.
+ * Injected into the tree's shadow root, where outside CSS cannot reach.
+ * The search box is hidden unless the host carries the filter-bridge marker
+ * (the library always renders it), and the drag-hover row gets a quiet ring
+ * — the library's selection background is illegible with xtralab's colors.
  */
 const FILE_TREE_UNSAFE_CSS =
   '[data-type="item"][data-item-selected="true"] ' +
@@ -114,26 +82,36 @@ const FILE_TREE_UNSAFE_CSS =
   'box-shadow: inset 0 0 0 2px var(--trees-accent);' +
   '}';
 
+/**
+ * Props for {@link FileBrowserComponent}.
+ */
 interface IFileBrowserProps {
+  /**
+   * The Jupyter contents manager backing the tree.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * The document manager used to rename files on drag-and-drop moves.
+   */
   docManager: IDocumentManager;
+  /**
+   * Called with the server path of an activated file.
+   */
   onOpenFile?: (serverPath: string) => void;
+  /**
+   * The application translator; defaults to `nullTranslator`.
+   */
   translator?: ITranslator;
   /**
-   * The host widget. Selection-change events are pushed up so context-menu
-   * commands can react to what the user has selected.
+   * The host widget; selection changes are pushed up for command handlers.
    */
   widget?: XtralabFileBrowser;
 }
 
 /**
- * Renders a `@pierre/trees` file tree backed by the Jupyter contents API.
- *
- * The Jupyter contents API only returns one directory level per request, so
- * the tree is populated lazily: the root is fetched on mount, and each
- * directory is fetched the first time the user expands it. Expansion is
- * detected by subscribing to the model and diffing against an in-memory load
- * state map.
+ * A `@pierre/trees` file tree backed by the Jupyter contents API. The API
+ * returns one directory level per request, so directories load lazily on
+ * first expand, detected by diffing the model against a load-state map.
  */
 export function FileBrowserComponent(
   props: IFileBrowserProps
@@ -159,26 +137,17 @@ export function FileBrowserComponent(
 
   React.useEffect(() => {
     const knownDirs = new Map<string, LoadState>();
-    // Mirror of the canonical paths currently loaded into the tree. Kept in
-    // sync with `model.resetPaths`/`model.batch`/`model.add` so we can
-    // re-test every loaded path against the gitignore matcher whenever
-    // either side changes — the model itself does not expose a
-    // path-iteration API.
+    // Mirror of the loaded canonical paths — the model has no path-iteration
+    // API, and the gitignore matcher must re-test every loaded path.
     const loadedPaths = new Set<string>();
     let gitignoreMatcher: Ignore | null = null;
     let gitStatusEntries: readonly GitStatusEntry[] = [];
     let cancelled = false;
 
     /**
-     * Recompute the combined `GitStatusEntry` list from the current
-     * gitignore matcher and the latest porcelain status, then push it into
-     * the tree. Safe to call at any time: empty inputs result in an empty
-     * payload, which clears any statuses applied previously.
-     *
-     * Ignored entries go first so the porcelain entries win in the
-     * unlikely event of overlap (a tracked path that also matches a
-     * `.gitignore` rule). `@pierre/trees` lets later entries overwrite
-     * earlier ones in its internal `statusByPath` map.
+     * Push the combined gitignore + porcelain entries into the tree.
+     * Ignored entries go first so porcelain entries win on overlap —
+     * `@pierre/trees` lets later entries overwrite earlier ones.
      */
     const syncGitStatus = (): void => {
       const entries: GitStatusEntry[] = [];
@@ -196,12 +165,6 @@ export function FileBrowserComponent(
       model.setGitStatus(entries);
     };
 
-    /**
-     * Reload the workspace `.gitignore`, then re-apply the resulting
-     * ignored statuses. Called on initial mount and whenever the user
-     * triggers a refresh — the file may have been edited or created in
-     * between.
-     */
     const refreshGitignoreMatcher = async (): Promise<void> => {
       let next: Ignore | null = null;
       try {
@@ -216,12 +179,6 @@ export function FileBrowserComponent(
       syncGitStatus();
     };
 
-    /**
-     * Refresh the porcelain-derived git status entries and re-apply them
-     * to the tree. Runs on mount, on every refresh, and on a periodic
-     * poll so out-of-band changes (terminal `git add`, file edits saved
-     * outside the editor, …) become visible without explicit user action.
-     */
     const refreshGitStatus = async (): Promise<void> => {
       const next = await loadGitStatusEntries(GIT_REPO_PATH);
       if (cancelled) {
@@ -253,21 +210,16 @@ export function FileBrowserComponent(
             loadedPaths.add(path);
           }
         } else {
-          // Filter out paths already in the model. The path-store throws
-          // when an explicit directory is added a second time, so any
-          // entry created out-of-band (e.g. by the "new folder" command's
-          // `notifyPathAdded` callback) must be skipped here.
+          // The path-store throws when a path is added twice, and entries
+          // can arrive out-of-band (e.g. `notifyPathAdded`), so skip those.
           const operations: FileTreeBatchOperation[] = paths
             .filter(path => model.getItem(path) === null)
             .map(path => ({ type: 'add', path }));
           if (operations.length > 0) {
             model.batch(operations);
           }
-          // Mirror every directory child into `loadedPaths` regardless of
-          // whether it was just added or skipped above — paths skipped by
-          // the filter are already in the model from a prior add and so
-          // belong in the mirror too. `Set.add` is idempotent, so the
-          // duplicate adds are a no-op.
+          // Paths skipped above are already in the model from a prior add,
+          // so they belong in the mirror too.
           for (const path of paths) {
             loadedPaths.add(path);
           }
@@ -289,10 +241,8 @@ export function FileBrowserComponent(
     };
 
     /**
-     * Refresh every directory currently loaded into the tree. Walks down
-     * from the root through the previously-expanded subdirectories so the
-     * tree state mirrors what's on disk while preserving the user's
-     * expansion state.
+     * Re-fetch the root and every previously-expanded directory so the tree
+     * mirrors the disk while preserving the user's expansion state.
      */
     const refreshAll = async (): Promise<void> => {
       const expandedPaths = new Set<string>();
@@ -330,9 +280,8 @@ export function FileBrowserComponent(
 
       const allPaths: string[] = [...rootPaths];
 
-      // BFS through the previously-expanded subtree, fetching only the
-      // directories the user had opened so the refresh doesn't walk the
-      // entire workspace.
+      // Fetch only the previously-expanded subtree so the refresh doesn't
+      // walk the entire workspace.
       const subdirsByParent = new Map<string, string[]>();
       subdirsByParent.set(ROOT_LOAD_KEY, rootSubdirs);
       const queue = rootSubdirs.filter(s => expandedPaths.has(s));
@@ -359,8 +308,6 @@ export function FileBrowserComponent(
         }
       }
 
-      // Reset the tree contents and restore the load-state map so future
-      // expansions know which directories still need fetching.
       model.resetPaths(allPaths);
       loadedPaths.clear();
       for (const path of allPaths) {
@@ -376,19 +323,11 @@ export function FileBrowserComponent(
         }
       });
 
-      // Refresh the `.gitignore` matcher in case the file was edited
-      // since the last load, then re-apply the resulting statuses to the
-      // newly-loaded paths. The reload runs in parallel with the rest of
-      // the refresh — `refreshGitignoreMatcher` calls `syncGitStatus`
-      // itself when it completes. The porcelain status is also re-fetched
-      // here so a user-triggered refresh picks up out-of-band git changes
-      // immediately instead of waiting for the next poll tick.
+      // Each re-applies the statuses itself when it completes.
       void refreshGitignoreMatcher();
       void refreshGitStatus();
 
-      // Re-expand the directories that were expanded before the refresh.
-      // We have to do this after `resetPaths` because the reset starts
-      // every directory in its initial collapsed state.
+      // `resetPaths` starts every directory collapsed, so re-expand after it.
       for (const path of expandedPaths) {
         const item = model.getItem(path);
         if (item !== null && item.isDirectory()) {
@@ -398,20 +337,10 @@ export function FileBrowserComponent(
     };
 
     /**
-     * Auto-refresh tick: walk every directory currently loaded into the
-     * tree, fetch its children, and apply the per-directory diff as a
-     * single batched mutation. Unlike {@link refreshAll} this never calls
-     * `model.resetPaths`, so the user's expansion, selection, and scroll
-     * state survive every poll. Mirrors what the default JupyterLab file
-     * browser does for its single-directory view.
-     *
-     * A failed fetch for a single directory is treated as transient and
-     * is skipped without touching that directory's children — they may
-     * still be valid even if this one fetch lost the race with a server
-     * restart. A deleted directory eventually surfaces through its
-     * parent's diff: when the parent is re-fetched and no longer lists
-     * the missing child, the child is removed recursively from the tree
-     * and from the load-state tracking maps.
+     * Auto-refresh tick: diff every loaded directory and apply batched
+     * mutations without `resetPaths`, so expansion, selection, and scroll
+     * state survive. A failed fetch is skipped as transient; a deleted
+     * directory surfaces through its parent's diff and is removed recursively.
      */
     const quietRefresh = async (): Promise<void> => {
       if (cancelled) {
@@ -433,10 +362,8 @@ export function FileBrowserComponent(
         if (cancelled) {
           return;
         }
-        // Skip directories that were removed from `knownDirs` while we
-        // were processing an earlier sibling — the cascade cleanup below
-        // can prune deep subtrees, so a path captured at the start of
-        // the tick may already be gone.
+        // The cascade cleanup below can prune subtrees mid-tick, so a dir
+        // captured at the start may already be gone.
         if (knownDirs.get(dir) !== 'loaded') {
           continue;
         }
@@ -464,8 +391,6 @@ export function FileBrowserComponent(
           if (newChildren.has(lp)) {
             continue;
           }
-          // Disappeared since the last tick. Remove recursively so any
-          // descendants that were also being tracked go with it.
           ops.push({ type: 'remove', path: lp, recursive: true });
           removals.push(lp);
           if (lp.endsWith('/')) {
@@ -488,16 +413,13 @@ export function FileBrowserComponent(
               `xtralab: auto-refresh batch failed for "${dir}"`,
               err
             );
-            // Leave the bookkeeping mirrors untouched so the next tick
-            // sees the same starting state and tries again.
+            // Leave the mirrors untouched so the next tick retries.
             continue;
           }
           mutated = true;
 
-          // Apply the matching mirror updates only after the batch lands
-          // in the model. The cascade cleanup below mirrors the
-          // `recursive: true` removal semantics so descendants we were
-          // tracking don't linger in `loadedPaths` or `knownDirs`.
+          // Mirror updates only after the batch lands; the cascade below
+          // mirrors the `recursive: true` removal semantics.
           for (const r of removals) {
             loadedPaths.delete(r);
           }
@@ -527,8 +449,7 @@ export function FileBrowserComponent(
           }
         }
 
-        // Register newly-observed subdirectories so the next user expand
-        // triggers a fetch instead of being ignored.
+        // Untracked subdirectories would ignore their first expand.
         for (const subdir of fetched.subdirectories) {
           if (!knownDirs.has(subdir)) {
             knownDirs.set(subdir, 'unloaded');
@@ -542,24 +463,8 @@ export function FileBrowserComponent(
     };
 
     /**
-     * Reveal {@link canonicalPath} in the tree: load any unloaded
-     * ancestor directories, expand them, and select the target so it is
-     * scrolled into view. Tolerant of partially-loaded state so the
-     * editor breadcrumbs can call it on any path at any time without
-     * caring about what the tree has already fetched.
-     *
-     * Each ancestor is awaited *before* it is expanded — expanding a
-     * directory triggers the model's subscribe callback, which
-     * synchronously sets the directory's load state to `loading` and
-     * kicks off its own fetch in parallel. Awaiting that in-flight
-     * fetch would return immediately on the second await, leaving the
-     * children unloaded when we move to the next iteration.
-     */
-    /**
-     * Clear the tree selection and scroll back to the top. Invoked by
-     * the file browser widget's `scrollToRoot` method when the home
-     * crumb is clicked; gives that gesture visible feedback even when
-     * the sidebar is already focused on the file browser.
+     * Clear the selection and scroll to the top; gives the home-crumb
+     * gesture visible feedback even when the sidebar is already focused.
      */
     const goToRoot = (): void => {
       if (cancelled) {
@@ -574,13 +479,6 @@ export function FileBrowserComponent(
       }
     };
 
-    /**
-     * Collapse every currently expanded directory in the tree. Walks the
-     * `knownDirs` map (the canonical record of which directories have been
-     * observed in the tree) and calls `.collapse()` on each loaded
-     * directory whose handle reports `isExpanded()`. Unloaded directories
-     * are not expanded by definition, so they're skipped.
-     */
     const collapseAll = (): void => {
       if (cancelled) {
         return;
@@ -600,6 +498,12 @@ export function FileBrowserComponent(
       });
     };
 
+    /**
+     * Reveal `canonicalPath`: fetch and expand ancestors, then select and
+     * scroll to the target. Each ancestor is fetched *before* expanding —
+     * expansion starts the subscribe callback's own fetch, and awaiting that
+     * in-flight fetch resolves with the children still unloaded.
+     */
     const revealPath = async (canonicalPath: string): Promise<void> => {
       if (cancelled || canonicalPath.length === 0) {
         return;
@@ -612,9 +516,7 @@ export function FileBrowserComponent(
         return;
       }
 
-      // Build the ordered list of ancestor directory canonical paths.
-      // For "foo/bar/baz.txt" → ["foo/", "foo/bar/"].
-      // For "foo/bar/"       → ["foo/"].
+      // "foo/bar/baz.txt" → ["foo/", "foo/bar/"].
       const ancestors: string[] = [];
       let cumulative = '';
       for (let i = 0; i < segments.length - 1; i++) {
@@ -668,16 +570,14 @@ export function FileBrowserComponent(
         previous?.deselect();
       }
       target.select();
-      // `select` highlights the row; `scrollToPath` focuses it and scrolls it
-      // to the middle of the viewport, even when the row is virtualized out of
-      // the rendered window.
+      // `scrollToPath` focuses and scrolls even when the row is virtualized
+      // out of the rendered window.
       model.scrollToPath(canonicalPath, { focus: true, offset: 'center' });
     };
 
     /**
-     * Insert a newly-created path (typically from "new folder" or
-     * "duplicate") into the tree without doing a full refresh. Expands
-     * the parent so the user sees the newly created entry immediately.
+     * Insert a newly-created path without a full refresh and expand its
+     * parent so the entry is visible immediately.
      */
     const handlePathAdded = (canonicalPath: string): void => {
       if (model.getItem(canonicalPath) === null) {
@@ -690,9 +590,8 @@ export function FileBrowserComponent(
       }
       loadedPaths.add(canonicalPath);
       if (canonicalPath.endsWith('/') && !knownDirs.has(canonicalPath)) {
-        // The new directory has no children yet, so mark it as already
-        // loaded — there's nothing to fetch and we don't want a stale
-        // "unloaded" entry to trigger a fetch on the next expand.
+        // A new directory has no children; mark it loaded so a stale
+        // "unloaded" entry doesn't trigger a fetch on the next expand.
         knownDirs.set(canonicalPath, 'loaded');
       }
       syncGitStatus();
@@ -804,10 +703,6 @@ export function FileBrowserComponent(
       }
     };
 
-    /**
-     * The tree refused the drop and left its model untouched — almost
-     * always a name collision at the destination.
-     */
     const failedDrop = (error: string, context: FileTreeDropContext): void => {
       if (cancelled) {
         return;
@@ -866,13 +761,8 @@ export function FileBrowserComponent(
       standby: 'when-hidden'
     });
 
-    // Auto-refresh the file listing on the same cadence as the default
-    // JupyterLab file browser. Backoff on failures so a server-side
-    // outage doesn't hammer the API, and stand by when the tab is
-    // hidden so we don't run the polling loop while the user is in
-    // another tab. `auto: false` keeps the first tick from racing the
-    // initial `fetchDirectory(ROOT_LOAD_KEY)` above — the poll is
-    // started explicitly once the initial load is in flight.
+    // `auto: false` keeps the first tick from racing the initial root
+    // fetch above; the poll is started explicitly below.
     const listingPoll = new Poll({
       auto: false,
       name: '@xtralab/fileBrowser:listing',
@@ -886,27 +776,17 @@ export function FileBrowserComponent(
     });
     void listingPoll.start();
 
-    // Surface contents changes that happen inside JupyterLab (file save,
-    // rename, delete) without waiting for the next poll tick. The
-    // default file browser uses the same `fileChanged` signal for the
-    // same reason. We can't tell from the signal alone whether the
-    // change affects a path we're showing, so we just nudge the poll —
-    // it diffs the loaded directories and emits no batch ops when
-    // nothing relevant changed.
+    // In-app contents changes (save, rename, delete) nudge the poll; the
+    // signal doesn't say whether a shown path is affected, the diff does.
     const onContentsFileChanged = (): void => {
       void listingPoll.refresh();
     };
     contentsManager.fileChanged.connect(onContentsFileChanged);
 
     const unsubscribe = model.subscribe(() => {
-      // Search-driven expansion must not trigger fetches: the tree
-      // auto-expands every directory whose path matches the query, and
-      // treating those as user expansions would recursively fetch every
-      // matching subtree — a single common letter can walk the whole
-      // workspace, node_modules included. Closing the search restores
-      // the pre-search expansion state, and a directory clicked in the
-      // results is toggled after the session closes, so real expansions
-      // are still fetched the moment the session ends.
+      // Search auto-expands every matching directory — fetching those would
+      // walk whole subtrees (node_modules included); real expansions still
+      // fetch once the search session closes.
       if (model.isSearchOpen()) {
         return;
       }
@@ -983,11 +863,8 @@ export function FileBrowserComponent(
     };
   }, [model, contentsManager, widget, docManager, trans]);
 
-  // Bridge the tree's selection state up to the widget so command handlers
-  // can read it without depending on React internals. The tree exposes its
-  // selection through `getSelectedPaths()` and emits a generic notification
-  // through `subscribe`, so we diff against a snapshot to avoid spamming the
-  // widget on every unrelated mutation.
+  // Bridge the tree selection up to the widget. `subscribe` fires on every
+  // mutation, so diff against a snapshot before notifying.
   React.useEffect(() => {
     if (widget === undefined) {
       return;
@@ -1011,13 +888,9 @@ export function FileBrowserComponent(
     };
   }, [model, widget]);
 
-  // Bridge the filter-box visibility between the widget and the tree. The
-  // widget owns the flag; applying it stamps the marker attribute the
-  // unsafeCSS rule keys on and opens or closes the model's search session
-  // (opening focuses the input, closing clears any active filter). The
-  // model subscription covers the reverse direction: typing a printable
-  // character while the tree has focus opens a session on the tree's own
-  // initiative, and the box must surface for that session to be usable.
+  // Applying the widget's filter flag stamps the marker the unsafeCSS rule
+  // keys on and syncs the search session; the subscription surfaces the box
+  // when the tree opens a session itself (typing while focused).
   React.useEffect(() => {
     if (widget === undefined) {
       return;
@@ -1085,21 +958,9 @@ export function FileBrowserComponent(
     };
   }, [onOpenFile]);
 
-  // Bridge contextmenu events out of the `<file-tree-container>` shadow DOM.
-  //
-  // `@pierre/trees` mounts the tree under an open shadow root attached to the
-  // `<file-tree-container>` custom element. When the user right-clicks a row
-  // inside the shadow tree, the event is retargeted to the host element when
-  // observed from the light DOM, and `app.contextMenu` walks via
-  // `parentElement` — it never enters the shadow tree, so the `[data-type=
-  // "item"]` selectors registered in `schema/plugin.json` never match.
-  //
-  // We listen in the capture phase (so we run before the application's
-  // document-level handler) and copy the right-clicked row's data attributes
-  // onto the host. Lumino then matches the host as if it were the row, and
-  // `app.contextMenuHitTest` from command handlers reads the same attributes
-  // back to recover the path. When the right-click misses any row we clear
-  // the attributes so empty-area clicks don't show stale per-item entries.
+  // Lumino never enters the tree's shadow DOM, so the `[data-type="item"]`
+  // selectors can't match rows; mirror the right-clicked row's data
+  // attributes onto the host (capture phase, cleared on a miss).
   React.useEffect(() => {
     const wrapper = wrapperRef.current;
     if (wrapper === null) {