xtralab 0.15.0 → 0.15.2

package/src/editorBreadcrumbs/index.ts

@@ -21,6 +21,10 @@ const PLUGIN_ID = 'xtralab:editor-breadcrumbs';
 const EDITOR_FACTORY = 'Editor';
 const TOOLBAR_ITEM_NAME = 'xtralab-editor-breadcrumbs';
 
+/**
+ * A widget extension that adds an `EditorBreadcrumbs` item to the toolbar of
+ * each new editor widget.
+ */
 class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
   IDocumentWidget<Widget, DocumentRegistry.IModel>,
   DocumentRegistry.IModel
@@ -30,6 +34,9 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
     this._trans = trans;
   }
 
+  /**
+   * Create the breadcrumbs toolbar item for a new editor widget.
+   */
   createNew(
     widget: IDocumentWidget<Widget, DocumentRegistry.IModel>,
     context: DocumentRegistry.IContext<DocumentRegistry.IModel>
@@ -56,12 +63,9 @@ class EditorBreadcrumbsExtension implements DocumentRegistry.IWidgetExtension<
 }
 
 /**
- * Adds a VS Code-style path breadcrumb to text editor toolbars. Each
- * segment is clickable: clicking dispatches `xtralab:reveal-path` so
- * any plugin that listens (today, the file browser) can surface the
- * underlying folder or file. The breadcrumbs plugin therefore does not
- * import the file browser at all — the JupyterLab command registry is
- * the only seam between them.
+ * Adds a clickable path breadcrumb to text editor toolbars. Clicks dispatch
+ * `xtralab:reveal-path`; the command registry is the only seam with the file
+ * browser.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,

package/src/editorBreadcrumbs/widget.ts

@@ -15,15 +15,25 @@ const CURRENT_ITEM_CLASS = 'jp-mod-current';
 const SEPARATOR_CLASS = 'jp-BreadCrumbs-separator';
 
 /**
- * Command dispatched when the user clicks a breadcrumb segment.
- * Registered by the file browser plugin; the breadcrumbs only know
- * the name so they stay decoupled from the file browser internals.
+ * Registered by the file browser plugin; only the name is shared here.
  */
 const REVEAL_COMMAND = 'xtralab:reveal-path';
 
+/**
+ * The options used to create an `EditorBreadcrumbs` widget.
+ */
 interface IEditorBreadcrumbsOptions {
+  /**
+   * The document context whose path is rendered.
+   */
   context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+  /**
+   * The command registry used to dispatch the reveal command.
+   */
   commands: CommandRegistry;
+  /**
+   * The application translation bundle.
+   */
   trans: TranslationBundle;
 }
 
@@ -38,9 +48,8 @@ export class EditorBreadcrumbs extends Widget {
     this._commands = options.commands;
     this._trans = options.trans;
     this.addClass(EDITOR_BREADCRUMBS_CLASS);
-    // The breadcrumbs stretch to fill the toolbar, so ReactiveToolbar's
-    // overflow math must count them as a spacer (2px) — measured at their
-    // stretched clientWidth they would evict every item into the popup.
+    // ReactiveToolbar must count the stretched breadcrumbs as a spacer (2px);
+    // measured at clientWidth they would evict every item into the popup.
     this.addClass(TOOLBAR_SPACER_CLASS);
     this.node.setAttribute('aria-label', this._trans.__('Editor file path'));
 
@@ -55,6 +64,9 @@ export class EditorBreadcrumbs extends Widget {
     this._render();
   }
 
+  /**
+   * Dispose of the resources held by the widget.
+   */
   dispose(): void {
     if (this.isDisposed) {
       return;
@@ -81,9 +93,7 @@ export class EditorBreadcrumbs extends Widget {
     parts.forEach((part, index) => {
       const isLast = index === parts.length - 1;
       const subPath = parts.slice(0, index + 1).join('/');
-      // Canonical `@pierre/trees` paths: directories carry a trailing
-      // slash, files do not. Every part except the last names a folder
-      // along the way to the open file.
+      // Canonical @pierre/trees paths: directories carry a trailing slash.
       const canonical = isLast ? subPath : `${subPath}/`;
 
       const item = document.createElement('span');
@@ -117,19 +127,15 @@ export class EditorBreadcrumbs extends Widget {
     item.dataset.path = '/';
     item.tabIndex = 0;
     item.setAttribute('role', 'button');
-    // Empty canonical path: the reveal command treats this as the
-    // workspace-root gesture — surface the file browser, clear its
-    // selection, and scroll back to the top. The tree has no row for
-    // the workspace root itself.
+    // Empty path is the workspace-root gesture; the tree has no row for
+    // the root itself.
     this._attachReveal(item, '');
     return item;
   }
 
   /**
-   * Bind click and keyboard activation on a crumb element to the
-   * shared reveal command. Dispatch is best-effort: a failure to
-   * resolve or execute the command is logged but never thrown into
-   * the editor's toolbar.
+   * Bind click and keyboard activation on a crumb to the reveal command;
+   * dispatch failures are logged, never thrown into the toolbar.
    */
   private _attachReveal(element: HTMLElement, canonicalPath: string): void {
     const fire = (event: Event): void => {

package/src/editorIndent/index.ts

@@ -14,10 +14,8 @@ import detectIndent from 'detect-indent';
 const PLUGIN_ID = 'xtralab:editor-indent';
 
 /**
- * Mime types whose newly-created (or too-short-to-detect) files should default
- * to a 2-space indent. Matches Prettier's defaults for web languages; mime
- * types not listed here inherit whatever the user has set in JupyterLab.
- * Covers .ts/.tsx/.jsx/.js variants registered by `@jupyterlab/codemirror`.
+ * 2-space fallback for new or undetectable files, matching Prettier's
+ * web-language defaults; unlisted mime types keep the user's setting.
  */
 const FALLBACK_INDENT_BY_MIME: Record<string, number> = {
   'application/ecmascript': 2,
@@ -38,15 +36,20 @@ const FALLBACK_INDENT_BY_MIME: Record<string, number> = {
   'text/yaml': 2
 };
 
+/**
+ * The indentation resolved for a document.
+ */
 interface IResolvedIndent {
+  /**
+   * The string inserted per indent level (spaces or a tab), for `indentUnit`.
+   */
   unit: string;
+  /**
+   * The indent width in columns, for `EditorState.tabSize`.
+   */
   width: number;
 }
 
-/**
- * Run `detect-indent` against the file's content and convert its result into
- * something we can hand to CodeMirror.
- */
 function detectFromContent(text: string): IResolvedIndent | null {
   if (text.length === 0) {
     return null;
@@ -76,9 +79,8 @@ function resolveIndent(text: string, mimeType: string): IResolvedIndent | null {
 }
 
 function buildExtension(resolved: IResolvedIndent): Extension {
-  // `Prec.highest` keeps these values first in their respective facets so
-  // they beat both `defaultConfig` and per-editor `editorConfig.indentUnit`,
-  // both of which JupyterLab registers at default precedence.
+  // `Prec.highest` beats both `defaultConfig` and per-editor
+  // `editorConfig.indentUnit`, which JupyterLab registers at default precedence.
   return Prec.highest([
     indentUnit.of(resolved.unit),
     EditorState.tabSize.of(resolved.width)
@@ -86,18 +88,10 @@ function buildExtension(resolved: IResolvedIndent): Extension {
 }
 
 /**
- * Sniff each opened document's leading whitespace and configure CodeMirror's
- * `indentUnit` / `tabSize` to match. JupyterLab only exposes a single global
- * indent setting, which means TypeScript files written with 4-space indent and
- * Python files written with 2-space indent both look wrong in the same editor;
- * detecting from the file's own content sidesteps that without forcing every
- * project to share the same convention.
- *
- * Detection runs at editor-construction time and again on the first content
- * change — that second pass exists because JupyterLab's collaborative document
- * loader can settle the file body into the shared model after the editor view
- * already exists, in which case the factory would otherwise have only seen an
- * empty string.
+ * Sniff each document's indentation and configure CodeMirror's `indentUnit` /
+ * `tabSize` to match, since JupyterLab only has one global indent setting.
+ * Detection reruns on the first content change: the collaborative loader can
+ * settle the file body after the editor view exists, so the factory may see ''.
  */
 const plugin: JupyterFrontEndPlugin<void> = {
   id: PLUGIN_ID,

package/src/fileBrowser/commands.ts

@@ -21,6 +21,7 @@ import {
   fileIcon,
   filterIcon,
   IDisposableMenuItem,
+  LabIcon,
   newFolderIcon,
   RankedMenu,
   refreshIcon
@@ -28,19 +29,24 @@ import {
 import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 import { ContextMenu, Widget } from '@lumino/widgets';
 
+import {
+  CommandArguments as GitCommandArguments,
+  CommandIDs as GitCommandIDs
+} from '../git/commands';
+import type { IFileChange } from '../git/tokens';
 import { toCanonicalPath, toServerPath } from './contents';
+import { GIT_REPO_PATH } from './gitStatus';
 import { FILE_BROWSER_ID, IXtralabFileBrowser } from './widget';
 
 /**
- * Command identifiers exposed by the xtralab browser. We deliberately namespace
- * these under `xtralab:` rather than reusing the `filebrowser:` ids
- * because the core `filebrowser:*` commands look up a `FileBrowser` instance
- * via `IFileBrowserFactory.tracker` — our widget is not a `FileBrowser`, so
- * those handlers would never see it.
+ * Command ids for the xtralab browser. Namespaced `xtralab:` rather than
+ * reusing the `filebrowser:` ids: the core handlers resolve their target via
+ * `IFileBrowserFactory.tracker`, which never sees this widget.
  */
 export namespace CommandIDs {
   export const open = 'xtralab:open';
   export const openBrowserTab = 'xtralab:open-browser-tab';
+  export const openGitDiff = 'xtralab:open-git-diff';
   export const rename = 'xtralab:rename';
   export const del = 'xtralab:delete';
   export const duplicate = 'xtralab:duplicate';
@@ -56,27 +62,40 @@ export namespace CommandIDs {
 }
 
 /**
- * Submenu id used to host the dynamically populated "Open With" entries.
- * Distinct from the core file browser's `jp-contextmenu-open-with` so the
- * core's populator does not try to fill ours with items derived from the
- * default file browser's selection.
+ * "Open With" submenu id. Distinct from the core `jp-contextmenu-open-with`
+ * so the core's populator does not fill ours from its own selection.
  */
 const OPEN_WITH_SUBMENU_ID = 'jp-contextmenu-xtralab-open-with';
 
+/**
+ * Options for registering the xtralab file browser commands.
+ */
 interface IRegisterCommandsOptions {
+  /**
+   * The JupyterLab application the commands are registered on.
+   */
   app: JupyterFrontEnd;
+  /**
+   * The file browser widget the commands act on.
+   */
   browser: IXtralabFileBrowser;
+  /**
+   * The document manager used to resolve the current widget's file path.
+   */
   docManager: IDocumentManager;
+  /**
+   * The command palette the commands are added to, or `null` when unavailable.
+   */
   palette: ICommandPalette | null;
+  /**
+   * The translator for user-facing strings; `null` falls back to English.
+   */
   translator: ITranslator | null;
 }
 
 /**
- * Resolve the path of the item the user right-clicked. We prefer the
- * contextmenu event's target — that is how `app.contextMenu` resolves which
- * items match a selector — and fall back to the first item in the tree's
- * selection if the command was invoked without an active contextmenu event
- * (e.g. from the command palette).
+ * Path of the right-clicked item, from the contextmenu event's target;
+ * falls back to the tree selection when invoked without one (the palette).
  */
 function getTargetPath(
   app: JupyterFrontEnd,
@@ -92,11 +111,6 @@ function getTargetPath(
   return browser.selectedPaths[0];
 }
 
-/**
- * Resolve the kind of the item that was right-clicked, based on the data
- * attributes emitted by `@pierre/trees` rows. Returns `undefined` if no
- * contextmenu event is active or the target is not a tree item.
- */
 function getTargetKind(app: JupyterFrontEnd): 'file' | 'folder' | undefined {
   const node = app.contextMenuHitTest(
     n => n.dataset !== undefined && n.dataset.type === 'item'
@@ -106,14 +120,9 @@ function getTargetKind(app: JupyterFrontEnd): 'file' | 'folder' | undefined {
 }
 
 /**
- * Resolve the canonical paths the "Open" command should act on. When the
- * user right-clicks a row that is part of the current selection, every
- * selected file is opened — matching the default file browser, where
- * "Open" on any file in a multi-selection opens them all. If the
- * right-clicked row is *not* in the selection, only that row is opened.
- *
- * Folders are always filtered out: there is no "current directory" in
- * this tree, so opening a folder via "Open" is a no-op.
+ * Canonical paths "Open" acts on: the whole selection when the right-clicked
+ * row is part of it (matching the default browser), else just that row.
+ * Folders are filtered out — this tree has no "current directory".
  */
 function getOpenPaths(
   app: JupyterFrontEnd,
@@ -135,8 +144,22 @@ function getOpenPaths(
 }
 
 /**
- * True iff there is an actionable target for a command on the right-click.
+ * Git changes of the target file, at most one staged and one unstaged.
+ * Status paths are repo-relative; like the tree's git badges, this assumes
+ * the repo root is the server root.
  */
+function getTargetChanges(
+  app: JupyterFrontEnd,
+  browser: IXtralabFileBrowser
+): IFileChange[] {
+  const targetPath = getTargetPath(app, browser);
+  if (targetPath === undefined) {
+    return [];
+  }
+  const serverPath = toServerPath(targetPath);
+  return browser.gitChanges.filter(change => change.path === serverPath);
+}
+
 function hasTarget(
   app: JupyterFrontEnd,
   browser: IXtralabFileBrowser
@@ -145,11 +168,9 @@ function hasTarget(
 }
 
 /**
- * Resolve the directory used as the working directory for actions that
- * create a new file or folder. Folder selections become their own cwd;
- * file selections fall back to their parent. Returns the empty string
- * when the tree has no selection — that matches the contents API's
- * convention for "the root directory".
+ * Working directory for create actions: a selected folder is its own cwd, a
+ * file falls back to its parent; empty string (the contents-API root) when
+ * nothing is selected.
  */
 function getWorkingDirectory(browser: IXtralabFileBrowser): string {
   const first = browser.selectedPaths[0];
@@ -164,14 +185,10 @@ function getWorkingDirectory(browser: IXtralabFileBrowser): string {
 }
 
 /**
- * Resolve the main-area widget whose tab is the target of the current
- * context-menu event, or `null` when that target is not a document tab. The
- * shell stamps each tab's `data-id` with its widget id, so the right-clicked
- * tab resolves even when it is not the current one.
- *
- * Valid only during a context-menu invocation: `contextMenuHitTest` reads the
- * last context-menu event, which is not cleared when the menu closes, so
- * {@link documentPathToReveal} gates this to avoid resolving a stale tab.
+ * Main-area widget whose tab is the target of the current context-menu
+ * event, or `null`. `contextMenuHitTest` reads the last context-menu event,
+ * which is not cleared when the menu closes, so callers must gate against
+ * resolving a stale tab.
  */
 function contextMenuTabWidget(app: JupyterFrontEnd): Widget | null {
   const node = app.contextMenuHitTest(
@@ -190,10 +207,9 @@ function contextMenuTabWidget(app: JupyterFrontEnd): Widget | null {
 }
 
 /**
- * Resolve the document to reveal as a canonical `@pierre/trees` path: the
- * right-clicked tab when `fromContextMenu` is true (the file-tab menu),
- * otherwise the active main-area widget (the palette). A file's context
- * `path` is already canonical. Returns `undefined` when nothing resolves.
+ * Canonical path of the document to reveal: the right-clicked tab when
+ * `fromContextMenu` is true (the file-tab menu), else the active main-area
+ * widget (the palette).
  */
 function documentPathToReveal(
   app: JupyterFrontEnd,
@@ -211,14 +227,10 @@ function documentPathToReveal(
 }
 
 /**
- * Refresh the "Open With" submenu's items from the document factories that
- * can open the file under the right-click. Mirrors the
- * `@jupyterlab/filebrowser-extension:open-with` pattern: the schema declares
- * an empty submenu by id, and we look it up on the open context menu and
- * fill it before the user can hover.
- *
+ * Build the populator that fills the "Open With" submenu on every
+ * context-menu open, mirroring `filebrowser-extension:open-with`.
  * `preferredWidgetFactories(path)` is path-only, so the populator stays
- * synchronous and the submenu is ready before the user can hover over it.
+ * synchronous and the submenu is ready before the user can hover.
  */
 function makeOpenWithUpdater(
   app: JupyterFrontEnd,
@@ -255,17 +267,26 @@ function makeOpenWithUpdater(
         command: CommandIDs.open
       })
     );
+
+    const changes = getTargetChanges(app, browser);
+    if (changes.length > 0) {
+      items.push(submenu.addItem({ type: 'separator' }));
+      for (const change of changes) {
+        items.push(
+          submenu.addItem({
+            args: { group: change.group },
+            command: CommandIDs.openGitDiff
+          })
+        );
+      }
+    }
   };
 }
 
 /**
- * Register every xtralab command on the application command registry, attach
- * the items to the application context menu, and wire up the dynamic
- * "Open With" submenu populator.
- *
- * @returns A function that detaches the menu items and signal listener.
- *   The commands themselves are owned by the registry for the lifetime of
- *   the plugin.
+ * Register the xtralab commands, context-menu wiring, and the dynamic
+ * "Open With" populator. Returns a detach function; the commands themselves
+ * stay owned by the registry.
  */
 export function registerCommands(opts: IRegisterCommandsOptions): () => void {
   const { app, browser, docManager, palette, translator } = opts;
@@ -320,6 +341,32 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
+  commands.addCommand(CommandIDs.openGitDiff, {
+    label: args =>
+      args.group === 'staged'
+        ? trans.__('Git Diff (Staged)')
+        : trans.__('Git Diff (Working)'),
+    icon: LabIcon.resolve({ icon: 'git:diff' }).bindprops({
+      stylesheet: 'menuItem'
+    }),
+    execute: async (args: ReadonlyPartialJSONObject) => {
+      const change = getTargetChanges(app, browser).find(
+        candidate => candidate.group === args.group
+      );
+      if (change === undefined) {
+        return;
+      }
+      const diffArgs: GitCommandArguments.IOpenDiff = {
+        repoPath: GIT_REPO_PATH,
+        change
+      };
+      return commands.execute(
+        GitCommandIDs.openDiff,
+        diffArgs as unknown as ReadonlyPartialJSONObject
+      );
+    }
+  });
+
   commands.addCommand(CommandIDs.rename, {
     label: trans.__('Rename…'),
     icon: editIcon.bindprops({ stylesheet: 'menuItem' }),
@@ -496,23 +543,16 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Refresh the toggle's state however the filter is shown or hidden —
-  // the toolbar button, or the auto-show that kicks in when typing with
-  // the tree focused opens a search session.
+  // The filter can also auto-show when typing with the tree focused, so
+  // track visibility changes rather than the command's own executions.
   const onFilterVisibleChanged = (): void => {
     commands.notifyCommandChanged(CommandIDs.toggleFileFilter);
   };
   browser.fileFilterVisibleChanged.connect(onFilterVisibleChanged);
 
-  // Public reveal seam. Other plugins (editor breadcrumbs, future
-  // "reveal in tree" actions) call this command rather than depending
-  // on the file browser widget directly. Activating the sidebar is part
-  // of the contract: the tree is hidden behind a tab and a reveal that
-  // does not surface the panel would silently no-op from the user's
-  // point of view. An empty path is the "workspace root" gesture —
-  // there is no tree row for the root itself, so the browser is asked
-  // to scroll back to the top and clear its selection instead.
-  // The tree is movable, so surface whichever sidebar widget holds it.
+  // Public reveal seam for other plugins; an empty path is the workspace-root
+  // gesture (the root has no tree row of its own). The tree is movable, so
+  // surface whichever sidebar widget holds it.
   const activateTreeHost = (): void => {
     for (const area of ['left', 'right']) {
       for (const widget of app.shell.widgets(area)) {
@@ -538,8 +578,6 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Reveal the resolved document in the tree browser via the reveal-path
-  // command, which surfaces the sidebar and scrolls to the target.
   commands.addCommand(CommandIDs.revealInFileTree, {
     label: trans.__('Show in File Tree'),
     caption: trans.__('Show this file in the xtralab file browser'),
@@ -579,10 +617,8 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
   commands.addCommand(CommandIDs.newLauncher, {
     label: trans.__('New Launcher'),
     caption: trans.__('Open a new launcher'),
-    // Skip the `menuItem` bindprops the other commands use: this command
-    // lives on the toolbar, where the launcher-extension's blue button
-    // styling expects the raw `jp-icon3` paths from `addIcon` so it can
-    // recolor them against the brand background.
+    // Raw `addIcon`, no `menuItem` bindprops: the launcher-extension's blue
+    // toolbar-button styling recolors the raw `jp-icon3` paths.
     icon: addIcon,
     execute: () => {
       const cwd = getWorkingDirectory(browser);
@@ -590,34 +626,24 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
     }
   });
 
-  // Re-evaluate enabled/visible state when the user changes the tree
-  // selection, in case a command's predicate depends on the selection.
   browser.selectionChanged.connect(() => {
     for (const id of Object.values(CommandIDs)) {
       commands.notifyCommandChanged(id);
     }
   });
 
-  // This command's enabled state tracks the active widget, not the tree
-  // selection, so re-evaluate it on current-widget changes. `currentChanged`
-  // is optional on the shell interface.
   const onCurrentChanged = (): void => {
     commands.notifyCommandChanged(CommandIDs.revealInFileTree);
   };
   app.shell.currentChanged?.connect(onCurrentChanged);
 
-  // Also surface it in the palette (acts on the active editor); the file-tab
-  // context-menu entry is declared in `schema/plugin.json`.
   const paletteItem = palette?.addItem({
     command: CommandIDs.revealInFileTree,
     category: trans.__('File Browser')
   });
 
-  // The static items are declared in `schema/plugin.json` under
-  // `jupyter.lab.menus.context` so users can override or disable them. The
-  // schema also declares an empty submenu placeholder with id
-  // `OPEN_WITH_SUBMENU_ID`; we fill it on every open from the document
-  // factories that can open the right-clicked file.
+  // Static context-menu items live in `schema/plugin.json` so users can
+  // override them; the schema declares the empty "Open With" placeholder.
   const updateOpenWithMenu = makeOpenWithUpdater(app, browser);
   app.contextMenu.opened.connect(updateOpenWithMenu);
 
@@ -630,9 +656,8 @@ export function registerCommands(opts: IRegisterCommandsOptions): () => void {
 }
 
 /**
- * The names we register with the toolbar. Kept distinct from
- * {@link CommandIDs} because the toolbar API uses opaque names rather
- * than commands.
+ * Toolbar item names, distinct from {@link CommandIDs}: the toolbar API
+ * uses opaque names rather than commands.
  */
 export namespace ToolbarNames {
   export const newLauncher = 'new-launcher';
@@ -643,10 +668,8 @@ export namespace ToolbarNames {
 }
 
 /**
- * Populate the file browser's toolbar with the buttons that mirror the
- * default JupyterLab file browser: a "+" launcher button, a new-folder
- * button, a refresh button, a collapse-all button, and the file filter
- * toggle.
+ * Populate the toolbar with the buttons that mirror the default JupyterLab
+ * file browser.
  */
 export function populateToolbar(opts: {
   app: JupyterFrontEnd;

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;