xtralab 0.15.0 → 0.15.2

package/lib/git/diffSurface.js

@@ -1,129 +1,33 @@
 import * as React from 'react';
 import { undoIcon } from '@jupyterlab/ui-components';
 import { FileDiff } from '@pierre/diffs/react';
+import { IconDiffSplit, IconDiffUnified, IconWordWrap } from '@pierre/icons';
 import { diffAcceptRejectHunk, parseDiffFromFile } from '@pierre/diffs';
 import { ImageDiffView, imageDataType } from './imageDiff';
 import { buildNotebookDiff, NotebookDiffView } from './notebookDiff';
-import { resolveDiffTheme } from './diffTheme';
-/**
- * The CSS class added to the diff main-area widget. The selectors that
- * style the embedded `@pierre/diffs` viewer hang off this class.
- */
+import { DEFAULT_SPLIT_RATIO, MAX_SPLIT_RATIO, MIN_SPLIT_RATIO } from './diffPreferences';
+import { DIFF_SCROLLBAR_CSS, resolveDiffTheme } from './diffTheme';
 export const DIFF_WIDGET_CSS_CLASS = 'jp-xtralab-DiffWidget';
 /**
- * `localStorage` key for the user's last-chosen split ratio, persisted so
- * the preference survives reloads (the library has no built-in way to
- * remember it).
- */
-const SPLIT_RATIO_STORAGE_KEY = 'xtralab:diff-split-ratio';
-/**
- * Bounds on the left-pane fraction. Keeping a few percent on either side
- * guarantees both panes remain visible — dragging to 0/100 would hide a
- * column and is almost never what the user wants.
- */
-const MIN_SPLIT_RATIO = 0.1;
-const MAX_SPLIT_RATIO = 0.9;
-const DEFAULT_SPLIT_RATIO = 0.5;
-/**
- * CSS injected via the `@pierre/diffs` `unsafeCSS` option. The library
- * places it inside the shadow root under `@layer unsafe`, which beats
- * the library's own `@layer base` rule that hardcodes
- * `grid-template-columns: 1fr 1fr` on the split-mode container.
- *
- * The override reads from `--xtralab-split-cols`, a custom property we set
- * on the host element via the `style` prop. Custom properties inherit
- * through the shadow DOM boundary, so adjusting it on the host instantly
- * resizes the columns without re-rendering the diff.
+ * Injected via the `unsafeCSS` option into the shadow root's `@layer
+ * unsafe`, beating the library's base rule that hardcodes `1fr 1fr`. Reads
+ * `--xtralab-split-cols` set on the host — custom properties cross the
+ * shadow boundary, so resizing needs no re-render.
  */
 const SPLIT_RESIZE_CSS = `pre[data-diff-type="split"][data-overflow="scroll"] {
   grid-template-columns: var(--xtralab-split-cols, 1fr 1fr);
 }`;
-function readStoredSplitRatio() {
-    try {
-        const raw = window.localStorage.getItem(SPLIT_RATIO_STORAGE_KEY);
-        if (raw === null) {
-            return DEFAULT_SPLIT_RATIO;
-        }
-        const parsed = Number.parseFloat(raw);
-        if (Number.isFinite(parsed) &&
-            parsed >= MIN_SPLIT_RATIO &&
-            parsed <= MAX_SPLIT_RATIO) {
-            return parsed;
-        }
-    }
-    catch (_a) {
-        // localStorage may throw in privacy mode or sandboxed contexts. Falling
-        // back to the default is fine — the user can resize again on this run.
-    }
-    return DEFAULT_SPLIT_RATIO;
-}
-function writeStoredSplitRatio(ratio) {
-    try {
-        window.localStorage.setItem(SPLIT_RATIO_STORAGE_KEY, ratio.toString());
-    }
-    catch (_a) {
-        // See readStoredSplitRatio — best-effort persistence.
-    }
-}
-const DIFF_STYLE_STORAGE_KEY = 'xtralab:diff-style';
-export function readStoredDiffStyle() {
-    try {
-        const raw = window.localStorage.getItem(DIFF_STYLE_STORAGE_KEY);
-        if (raw === 'split' || raw === 'unified') {
-            return raw;
-        }
-    }
-    catch (_a) {
-        // See readStoredSplitRatio — privacy-mode / sandboxed contexts can throw.
-    }
-    return 'split';
-}
-export function writeStoredDiffStyle(style) {
-    try {
-        window.localStorage.setItem(DIFF_STYLE_STORAGE_KEY, style);
-    }
-    catch (_a) {
-        // Best-effort.
-    }
-}
-const NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY = 'xtralab:notebook-diff-view-mode';
-export function readStoredNotebookViewMode() {
-    try {
-        const raw = window.localStorage.getItem(NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY);
-        if (raw === 'json' || raw === 'notebook') {
-            return raw;
-        }
-    }
-    catch (_a) {
-        // See readStoredSplitRatio — privacy-mode / sandboxed contexts can
-        // throw on access. The notebook view is the better default anyway.
-    }
-    return 'notebook';
-}
-export function writeStoredNotebookViewMode(mode) {
-    try {
-        window.localStorage.setItem(NOTEBOOK_DIFF_VIEW_MODE_STORAGE_KEY, mode);
-    }
-    catch (_a) {
-        // Best-effort.
-    }
-}
+const DIFF_SURFACE_CSS = `${SPLIT_RESIZE_CSS}\n${DIFF_SCROLLBAR_CSS}`;
 /**
- * Detect notebook files by extension. We only look at the suffix so the
- * caller doesn't need to plumb a content-type field through; mistaking
- * another `.ipynb`-named file for a notebook is harmless because
- * {@link buildNotebookDiff} validates the JSON shape and we fall back to
- * the file diff if parsing fails.
+ * Extension-only check; a false positive is harmless because
+ * {@link buildNotebookDiff} validates the JSON and the file diff is the fallback.
  */
 function isNotebookPath(path) {
     return path.toLowerCase().endsWith('.ipynb');
 }
 /**
- * Decide whether the active JupyterLab theme is a dark theme. Prefers the
- * `IThemeManager` token when available, and falls back to sniffing the
- * `data-jp-theme-light` attribute that JupyterLab sets on `<body>` so the
- * component still works in stripped-down hosts where the token isn't
- * provided (lite, certain notebook configurations, …).
+ * Dark-theme check via `IThemeManager`, falling back to the
+ * `data-jp-theme-light` body attribute for hosts without the token.
  */
 export function isDarkTheme(themeManager) {
     if (themeManager !== null && themeManager.theme !== null) {
@@ -143,16 +47,12 @@ export function isPierreTheme(themeManager) {
  * Shared renderer for text, notebook and image diffs.
  */
 export function DiffSurface(props) {
-    const { loading, error, isBinary, oldText, newText, newName, oldName, dark, pierreTheme, rendermime, notebookViewMode, diffStyle, onNotebookAvailabilityChange, onFileDiffActiveChange, onMetadataChange, hunkDiscard, onLineAsk, trans } = props;
+    const { loading, error, isBinary, oldText, newText, newName, oldName, dark, pierreTheme, rendermime, notebookViewMode, diffStyle, lineWrap, splitRatio, onSplitRatioChange, imageViewMode, onImageViewModeChange, onNotebookAvailabilityChange, onFileDiffActiveChange, onMetadataChange, hunkDiscard, onLineAsk, trans } = props;
     const hasContent = !loading && error === null && !isBinary;
-    // Raster images take a dedicated `<img>`-based view instead of a
-    // text/notebook diff; the host passes the two sides as base64 strings in
-    // `oldText`/`newText` (the git server base64-encodes binary content).
+    // For raster images the host passes both sides as base64 in oldText/newText.
     const imageType = React.useMemo(() => imageDataType(newName), [newName]);
-    // Pre-compute the line-oriented diff metadata. Owning it here lets us
-    // pass it to {@link FileDiff} *and* thread the same instance through
-    // {@link diffAcceptRejectHunk} when the user discards a hunk — so hunk
-    // indexes line up between what the user clicked and what we mutate.
+    // Owning the metadata here keeps hunk indexes aligned between FileDiff
+    // and diffAcceptRejectHunk on discard.
     const metadata = React.useMemo(() => {
         if (!hasContent || imageType !== null) {
             return null;
@@ -164,47 +64,35 @@ export function DiffSurface(props) {
         const newFile = { name: newName, contents: newText };
         return parseDiffFromFile(oldFile, newFile);
     }, [hasContent, imageType, oldText, newText, oldName, newName]);
-    // Cell-by-cell notebook diff for `.ipynb` files. When non-null the
-    // renderer uses a notebook-aware view instead of the line-oriented file
-    // diff — kept distinct from {@link metadata} so a notebook whose JSON we
-    // cannot parse can fall back to the file diff path.
     const notebookDiff = React.useMemo(() => {
         if (!hasContent || imageType !== null || !isNotebookPath(newName)) {
             return null;
         }
         return buildNotebookDiff({ oldText, newText });
     }, [hasContent, imageType, oldText, newText, newName]);
-    // Tell the host whether a rendered notebook view is currently available
-    // so it can show/hide its Notebook/JSON toggle.
     React.useEffect(() => {
         onNotebookAvailabilityChange === null || onNotebookAvailabilityChange === void 0 ? void 0 : onNotebookAvailabilityChange(notebookDiff !== null);
     }, [onNotebookAvailabilityChange, notebookDiff]);
-    // Report the diff shape so hosts can react (e.g. auto-close on empty).
     React.useEffect(() => {
         onMetadataChange === null || onMetadataChange === void 0 ? void 0 : onMetadataChange({
             hunkCount: metadata !== null ? metadata.hunks.length : null
         });
     }, [onMetadataChange, metadata]);
-    // Decide which view to render. The notebook view requires a successful
-    // nbformat parse; if that failed, we only show the raw JSON file diff.
-    // Computed before the early returns below so the file-diff-active effect
-    // can depend on it without violating the rules of hooks.
+    // Computed before the early returns so the hooks below can depend on
+    // them without breaking the rules of hooks.
     const hasNotebookView = notebookDiff !== null;
     const showNotebookView = hasNotebookView && notebookViewMode === 'notebook';
     const showFileDiff = !showNotebookView && metadata !== null;
-    // The split vs unified choice only affects the textual/code file diff, so
-    // tell the host whether that view is active to drive its Split/Unified
-    // toolbar toggle.
     React.useEffect(() => {
         onFileDiffActiveChange === null || onFileDiffActiveChange === void 0 ? void 0 : onFileDiffActiveChange(showFileDiff);
     }, [onFileDiffActiveChange, showFileDiff]);
-    // Split ratio for the diff columns: fraction of width given to the
-    // deletions (left) pane. Persisted across sessions so the user only
-    // dials in their layout once.
-    const [leftRatio, setLeftRatio] = React.useState(() => readStoredSplitRatio());
+    // Local while dragging; the host hears the ratio when a drag ends.
+    const [leftRatio, setLeftRatio] = React.useState(splitRatio);
+    React.useEffect(() => {
+        setLeftRatio(splitRatio);
+    }, [splitRatio]);
     const wrapperRef = React.useRef(null);
-    // The drag handler reads the live ratio from a ref so the listeners we
-    // attach on pointer-down don't capture a stale value across renders.
+    // Drag listeners read the live ratio from a ref to avoid stale captures.
     const leftRatioRef = React.useRef(leftRatio);
     React.useEffect(() => {
         leftRatioRef.current = leftRatio;
@@ -216,8 +104,6 @@ export function DiffSurface(props) {
         }
         return metadata.hunks.map((hunk, hunkIndex) => ({
             side: 'additions',
-            // The first line of each hunk in the new file. We anchor the button
-            // there so it sits at the top of the hunk's body.
             lineNumber: hunk.additionStart,
             metadata: { hunkIndex }
         }));
@@ -227,12 +113,8 @@ export function DiffSurface(props) {
             return;
         }
         const updated = diffAcceptRejectHunk(metadata, hunkIndex, 'reject');
-        // `additionLines` after a 'reject' contains the full new file with
-        // the hunk reverted back to the old content. The library splits
-        // file contents with `/(?<=\n)/` (a lookbehind that keeps the
-        // trailing `\n` on each line), so the entries already carry their
-        // own line endings — joining with `''` rebuilds the original text
-        // verbatim, while joining with `'\n'` would double every newline.
+        // additionLines holds the full new file with the hunk reverted; lines keep
+        // their trailing `\n` (lookbehind split), so join('') rebuilds it verbatim.
         const text = updated.additionLines.join('');
         try {
             await hunkDiscard.save(text);
@@ -256,15 +138,11 @@ export function DiffSurface(props) {
         if (onLineAsk === undefined) {
             return;
         }
-        // Anchor to the gutter "+" button that was just clicked. It lives in
-        // the `@pierre/diffs` shadow root (which is open), parked on the
-        // hovered/selected line's number element.
+        // Anchor to the just-clicked gutter "+" button inside the library's open shadow root.
         const slot = (_c = (_b = (_a = wrapperRef.current) === null || _a === void 0 ? void 0 : _a.querySelector('diffs-container')) === null || _b === void 0 ? void 0 : _b.shadowRoot) === null || _c === void 0 ? void 0 : _c.querySelector('[data-gutter-utility-slot]');
         onLineAsk(range, slot instanceof Element ? slot.getBoundingClientRect() : null);
     }, [onLineAsk]);
     const handleResizerPointerDown = React.useCallback((event) => {
-        // Only react to primary-button drags. Right-click / middle-click on
-        // the handle should pass through to the browser default.
         if (event.button !== 0) {
             return;
         }
@@ -293,18 +171,16 @@ export function DiffSurface(props) {
             handle.removeEventListener('pointermove', onPointerMove);
             handle.removeEventListener('pointerup', onPointerEnd);
             handle.removeEventListener('pointercancel', onPointerEnd);
-            // Only persist on drag-end so a quick drag isn't followed by a
-            // burst of writes for every intermediate position.
-            writeStoredSplitRatio(leftRatioRef.current);
+            onSplitRatioChange(leftRatioRef.current);
         };
         handle.addEventListener('pointermove', onPointerMove);
         handle.addEventListener('pointerup', onPointerEnd);
         handle.addEventListener('pointercancel', onPointerEnd);
-    }, []);
+    }, [onSplitRatioChange]);
     const handleResizerDoubleClick = React.useCallback(() => {
         setLeftRatio(DEFAULT_SPLIT_RATIO);
-        writeStoredSplitRatio(DEFAULT_SPLIT_RATIO);
-    }, []);
+        onSplitRatioChange(DEFAULT_SPLIT_RATIO);
+    }, [onSplitRatioChange]);
     const handleResizerKeyDown = React.useCallback((event) => {
         const step = event.shiftKey ? 0.1 : 0.01;
         let next = null;
@@ -328,8 +204,8 @@ export function DiffSurface(props) {
         event.preventDefault();
         const clamped = Math.max(MIN_SPLIT_RATIO, Math.min(MAX_SPLIT_RATIO, next));
         setLeftRatio(clamped);
-        writeStoredSplitRatio(clamped);
-    }, []);
+        onSplitRatioChange(clamped);
+    }, [onSplitRatioChange]);
     if (loading) {
         return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, trans.__('Loading diff…')));
     }
@@ -340,49 +216,32 @@ export function DiffSurface(props) {
         return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, trans.__('Binary file — diff not supported.')));
     }
     if (imageType !== null) {
-        // `oldText`/`newText` carry the two revisions as base64 here. The
-        // image view owns its own layout and mode selector, so it does not
-        // use the split resizer or the notebook/JSON toggle.
         return (React.createElement("div", { className: "jp-xtralab-DiffWidget-content" },
-            React.createElement(ImageDiffView, { reference: oldText, challenger: newText, fileType: imageType, trans: trans })));
+            React.createElement(ImageDiffView, { reference: oldText, challenger: newText, fileType: imageType, mode: imageViewMode, onModeChange: onImageViewModeChange, trans: trans })));
     }
     if (!showNotebookView && !showFileDiff) {
         return (React.createElement("div", { className: "jp-xtralab-DiffWidget-status" }, trans.__('No content to diff.')));
     }
-    // Custom property set on the diffs-container host. The library's
-    // shadow-root rule consumes it via `var(--xtralab-split-cols, …)` (see
-    // SPLIT_RESIZE_CSS) and recomputes the column tracks instantly. Only
-    // relevant in the file-diff path; the notebook view doesn't use it.
     const leftPercent = leftRatio * 100;
+    // The wrapped split grid sizes its gutter tracks to their content, so a
+    // percentage split cannot line up with the handle.
+    const showResizer = showFileDiff && diffStyle === 'split' && !lineWrap;
     const hostStyle = {
         '--xtralab-split-cols': `${leftPercent}% ${100 - leftPercent}%`
     };
     return (React.createElement("div", { className: "jp-xtralab-DiffWidget-content" },
         React.createElement("div", { ref: wrapperRef, className: "jp-xtralab-DiffWidget-body" },
             React.createElement("div", { className: "jp-xtralab-DiffWidget-scroll" }, showNotebookView && notebookDiff !== null ? (React.createElement(NotebookDiffView, { diff: notebookDiff, dark: dark, pierreTheme: pierreTheme, rendermime: rendermime, trans: trans })) : showFileDiff && metadata !== null ? (React.createElement(FileDiff, { fileDiff: metadata, lineAnnotations: lineAnnotations, renderAnnotation: renderAnnotation, style: hostStyle, 
-                // Disable the worker pool: JupyterLab's webpack federation
-                // pipeline doesn't ship the library's
-                // `@pierre/diffs/worker/worker.js` file at a URL the worker
-                // bootstrap can resolve from, so leaving the pool enabled
-                // crashes on instantiation. Running on the main thread is
-                // fine for the small files git diffs typically operate on.
+                // JupyterLab's federation pipeline can't serve the worker bundle
+                // at a resolvable URL, so the pool crashes; run on the main thread.
                 disableWorkerPool: true, options: {
                     diffStyle,
-                    // Drop the file header — the tab title already shows the
-                    // file name and the panel header carries the change
-                    // context.
+                    overflow: lineWrap ? 'wrap' : 'scroll',
                     disableFileHeader: true,
                     theme: resolveDiffTheme(dark, pierreTheme),
                     themeType: dark ? 'dark' : 'light',
-                    // Inject the column-resize override into the shadow root
-                    // via the library's `@layer unsafe` channel. Keeping the
-                    // string constant lets the library short-circuit the
-                    // re-render path it uses when this option actually
-                    // changes.
-                    unsafeCSS: SPLIT_RESIZE_CSS,
-                    // Line selection + the gutter "+" button feed the
-                    // ask-agent popup; only wired up when a handler exists so
-                    // a plain diff keeps its passive gutter.
+                    // Constant string lets the library skip its unsafeCSS re-render path.
+                    unsafeCSS: DIFF_SURFACE_CSS,
                     ...(onLineAsk !== undefined
                         ? {
                             enableLineSelection: true,
@@ -391,13 +250,11 @@ export function DiffSurface(props) {
                         }
                         : {})
                 } })) : null),
-            showFileDiff && diffStyle === 'split' ? (React.createElement("div", { className: "jp-xtralab-DiffWidget-resizer", style: { left: `${leftPercent}%` }, role: "separator", "aria-orientation": "vertical", "aria-valuenow": Math.round(leftPercent), "aria-valuemin": Math.round(MIN_SPLIT_RATIO * 100), "aria-valuemax": Math.round(MAX_SPLIT_RATIO * 100), "aria-label": trans.__('Resize the diff panes'), tabIndex: 0, title: trans.__('Drag to resize the diff panes (double-click to reset)'), onPointerDown: handleResizerPointerDown, onDoubleClick: handleResizerDoubleClick, onKeyDown: handleResizerKeyDown })) : null)));
+            showResizer ? (React.createElement("div", { className: "jp-xtralab-DiffWidget-resizer", style: { left: `${leftPercent}%` }, role: "separator", "aria-orientation": "vertical", "aria-valuenow": Math.round(leftPercent), "aria-valuemin": Math.round(MIN_SPLIT_RATIO * 100), "aria-valuemax": Math.round(MAX_SPLIT_RATIO * 100), "aria-label": trans.__('Resize the diff panes'), tabIndex: 0, title: trans.__('Drag to resize the diff panes (double-click to reset)'), onPointerDown: handleResizerPointerDown, onDoubleClick: handleResizerDoubleClick, onKeyDown: handleResizerKeyDown })) : null)));
 }
 /**
- * Segmented Notebook/JSON selector. Hosts mount this into whatever toolbar
- * they own (the launcher's `MainAreaWidget` toolbar, or the
- * `jupyterlab-git`-provided diff toolbar) and drive its value/visibility
- * from the same state they pass to {@link DiffSurface}.
+ * Segmented Notebook/JSON selector. Hosts mount it into their own toolbar
+ * and drive value/visibility from the state they pass to {@link DiffSurface}.
  */
 export function NotebookViewModeControl(props) {
     const { mode, available, onChange, trans } = props;
@@ -409,37 +266,39 @@ export function NotebookViewModeControl(props) {
         React.createElement("button", { type: "button", role: "tab", "aria-selected": mode === 'json', "data-active": mode === 'json', className: "jp-xtralab-DiffWidget-segmentedButton", onClick: () => onChange('json') }, trans.__('JSON'))));
 }
 /**
- * Split / unified glyphs, inlined from the `@pierre/diffs` icon sprite
- * (`diffs-icon-diff-split` / `diffs-icon-diff-unified`) so the toggle looks
- * like the one on the library's own docs site without depending on the
- * sprite sheet being injected into the document. `currentColor` lets the
- * segmented-button styling drive the fill (including the active state).
- */
-function DiffSplitIcon() {
-    return (React.createElement("svg", { viewBox: "0 0 16 16", fill: "currentColor", "aria-hidden": "true" },
-        React.createElement("path", { d: "M14 0H8.5v16H14a2 2 0 0 0 2-2V2a2 2 0 0 0-2-2m-1.5 6.5v1h1a.5.5 0 0 1 0 1h-1v1a.5.5 0 0 1-1 0v-1h-1a.5.5 0 0 1 0-1h1v-1a.5.5 0 0 1 1 0" }),
-        React.createElement("path", { d: "M2 0a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h5.5V0zm.5 7.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1 0-1", opacity: ".3" })));
-}
-function DiffUnifiedIcon() {
-    return (React.createElement("svg", { viewBox: "0 0 16 16", fill: "currentColor", "aria-hidden": "true" },
-        React.createElement("path", { fillRule: "evenodd", d: "M16 14a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V8.5h16zm-8-4a.5.5 0 0 0-.5.5v1h-1a.5.5 0 0 0 0 1h1v1a.5.5 0 0 0 1 0v-1h1a.5.5 0 0 0 0-1h-1v-1A.5.5 0 0 0 8 10", clipRule: "evenodd" }),
-        React.createElement("path", { fillRule: "evenodd", d: "M14 0a2 2 0 0 1 2 2v5.5H0V2a2 2 0 0 1 2-2zM6.5 3.5a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1z", clipRule: "evenodd", opacity: ".4" })));
-}
-/**
- * Segmented Split/Unified selector. Mirrors {@link NotebookViewModeControl}:
- * hosts mount it into their own toolbar and drive its value/visibility from
- * the same state they pass to {@link DiffSurface}. Only meaningful while the
- * textual/code file diff is the active view, so `available` mirrors the
- * surface's `onFileDiffActiveChange`.
+ * Split/Unified selector: two segmented buttons, or with `control: 'toggle'`
+ * one button that shows the layout it switches to.
+ * `available` mirrors the surface's `onFileDiffActiveChange`.
  */
 export function DiffStyleControl(props) {
-    const { diffStyle, available, onChange, trans } = props;
+    const { diffStyle, control, available, onChange, trans } = props;
     if (!available) {
         return React.createElement(React.Fragment, null);
     }
+    if (control === 'toggle') {
+        const next = diffStyle === 'split' ? 'unified' : 'split';
+        const label = next === 'split'
+            ? trans.__('Switch to split view')
+            : trans.__('Switch to unified view');
+        return (React.createElement("div", { className: "jp-xtralab-DiffWidget-segmented" },
+            React.createElement("button", { type: "button", className: "jp-xtralab-DiffWidget-segmentedButton jp-xtralab-DiffWidget-segmentedButton-icon", title: label, "aria-label": label, onClick: () => onChange(next) }, next === 'split' ? React.createElement(IconDiffSplit, null) : React.createElement(IconDiffUnified, null))));
+    }
     return (React.createElement("div", { className: "jp-xtralab-DiffWidget-segmented", role: "tablist", "aria-label": trans.__('Diff view style') },
         React.createElement("button", { type: "button", role: "tab", "aria-selected": diffStyle === 'split', "data-active": diffStyle === 'split', className: "jp-xtralab-DiffWidget-segmentedButton jp-xtralab-DiffWidget-segmentedButton-icon", title: trans.__('Split (side-by-side) view'), "aria-label": trans.__('Split view'), onClick: () => onChange('split') },
-            React.createElement(DiffSplitIcon, null)),
+            React.createElement(IconDiffSplit, null)),
         React.createElement("button", { type: "button", role: "tab", "aria-selected": diffStyle === 'unified', "data-active": diffStyle === 'unified', className: "jp-xtralab-DiffWidget-segmentedButton jp-xtralab-DiffWidget-segmentedButton-icon", title: trans.__('Unified (inline) view'), "aria-label": trans.__('Unified view'), onClick: () => onChange('unified') },
-            React.createElement(DiffUnifiedIcon, null))));
+            React.createElement(IconDiffUnified, null))));
+}
+/**
+ * Line-wrap toggle styled as a one-button segmented control.
+ * `available` mirrors the surface's `onFileDiffActiveChange`.
+ */
+export function LineWrapControl(props) {
+    const { lineWrap, available, onChange, trans } = props;
+    if (!available) {
+        return React.createElement(React.Fragment, null);
+    }
+    return (React.createElement("div", { className: "jp-xtralab-DiffWidget-segmented" },
+        React.createElement("button", { type: "button", "aria-pressed": lineWrap, "data-active": lineWrap, className: "jp-xtralab-DiffWidget-segmentedButton jp-xtralab-DiffWidget-segmentedButton-icon", title: trans.__('Wrap long lines'), "aria-label": trans.__('Wrap lines'), onClick: () => onChange(!lineWrap) },
+            React.createElement(IconWordWrap, null))));
 }

package/lib/git/diffTheme.d.ts

@@ -1,4 +1,11 @@
 import { type DiffsThemeNames } from '@pierre/diffs';
+/**
+ * `unsafeCSS` for a taller, always-visible horizontal scrollbar. The library
+ * default is 6px and only paints the thumb on hover, in a color close to the
+ * background, so users miss that long lines scroll. Same thumb color as the
+ * app scrollbars in chrome.css.
+ */
+export declare const DIFF_SCROLLBAR_CSS = ":host {\n  --diffs-scrollbar-gutter-override: 10px;\n  --xtralab-diff-scrollbar-thumb: color-mix(in srgb, var(--jp-ui-font-color1) 28%, transparent);\n}\n[data-code]::-webkit-scrollbar-thumb {\n  background-color: var(--xtralab-diff-scrollbar-thumb);\n  border-width: 2px;\n  border-radius: 999px;\n}\n[data-code]::-webkit-scrollbar-thumb:hover {\n  background-color: color-mix(in srgb, var(--jp-ui-font-color1) 45%, transparent);\n}\n@supports (-moz-appearance: none) {\n  [data-code] {\n    scrollbar-color: var(--xtralab-diff-scrollbar-thumb) transparent;\n  }\n}";
 /**
  * Choose Pierre's palette or the JupyterLab CSS-variable theme.
  */

package/lib/git/diffTheme.js

@@ -20,6 +20,29 @@ registerCustomCSSVariableTheme(JUPYTERLAB_DIFF_THEME, {
     'token-punctuation': 'var(--jp-mirror-editor-punctuation-color)',
     'token-link': 'var(--jp-mirror-editor-link-color)'
 });
+/**
+ * `unsafeCSS` for a taller, always-visible horizontal scrollbar. The library
+ * default is 6px and only paints the thumb on hover, in a color close to the
+ * background, so users miss that long lines scroll. Same thumb color as the
+ * app scrollbars in chrome.css.
+ */
+export const DIFF_SCROLLBAR_CSS = `:host {
+  --diffs-scrollbar-gutter-override: 10px;
+  --xtralab-diff-scrollbar-thumb: color-mix(in srgb, var(--jp-ui-font-color1) 28%, transparent);
+}
+[data-code]::-webkit-scrollbar-thumb {
+  background-color: var(--xtralab-diff-scrollbar-thumb);
+  border-width: 2px;
+  border-radius: 999px;
+}
+[data-code]::-webkit-scrollbar-thumb:hover {
+  background-color: color-mix(in srgb, var(--jp-ui-font-color1) 45%, transparent);
+}
+@supports (-moz-appearance: none) {
+  [data-code] {
+    scrollbar-color: var(--xtralab-diff-scrollbar-thumb) transparent;
+  }
+}`;
 /**
  * Choose Pierre's palette or the JupyterLab CSS-variable theme.
  */

package/lib/git/diffWidget.d.ts

@@ -8,28 +8,55 @@ import { ReactWidget } from '@jupyterlab/ui-components';
 import { ISignal } from '@lumino/signaling';
 import { Widget } from '@lumino/widgets';
 import type { IAskAgent } from '../askAgent/tokens';
-import { DIFF_WIDGET_CSS_CLASS, type DiffStyle, type NotebookDiffViewMode } from './diffSurface';
+import { type IDiffPreferences } from './diffPreferences';
+import { DIFF_WIDGET_CSS_CLASS } from './diffSurface';
 export { DIFF_WIDGET_CSS_CLASS };
 /**
  * `Git.Diff.IModel` plus optional xtralab-only metadata.
  */
 export interface IXtralabDiffModel extends Git.Diff.IModel {
+    /**
+     * Whether the file is binary, so no text contents are fetched.
+     */
     isBinary?: boolean;
+    /**
+     * Whether hunks may be discarded; when absent, a working-tree heuristic decides.
+     */
     canDiscard?: boolean;
+    /**
+     * The old-side path when the diff represents a rename.
+     */
     oldFilename?: string;
 }
 /**
  * Application-level services the diff model does not carry.
  */
 export interface IXtralabDiffContext {
+    /**
+     * The contents manager used to save hunk-discard results.
+     */
     contentsManager: Contents.IManager;
+    /**
+     * The rendermime registry for rendered notebook diffs, or `null` to
+     * force the textual fallback.
+     */
     rendermime: IRenderMimeRegistry | null;
+    /**
+     * The theme manager used to track theme changes, or `null` to watch
+     * the body attribute instead.
+     */
     themeManager: IThemeManager | null;
     /**
-     * The ask-agent popup; when available, diff line selections get an
-     * "ask an agent about these lines" gutter button.
+     * When available, diff line selections get an "ask an agent" gutter button.
      */
     askAgent: IAskAgent | null;
+    /**
+     * The display choices shared by all diff views.
+     */
+    preferences: IDiffPreferences;
+    /**
+     * The application translation bundle.
+     */
     trans: TranslationBundle;
 }
 /**
@@ -37,6 +64,9 @@ export interface IXtralabDiffContext {
  */
 export declare class XtralabDiffWidget extends ReactWidget implements Git.Diff.IDiffWidget {
     constructor(model: Git.Diff.IModel, context: IXtralabDiffContext);
+    /**
+     * The git diff model being rendered.
+     */
     get model(): Git.Diff.IModel;
     /**
      * Swap the rendered model when the launcher reuses its preview tab.
@@ -54,41 +84,64 @@ export declare class XtralabDiffWidget extends ReactWidget implements Git.Diff.I
      * Re-pull both sides of the model and re-render.
      */
     refresh(): Promise<void>;
-    get notebookViewMode(): NotebookDiffViewMode;
-    setNotebookViewMode(mode: NotebookDiffViewMode): void;
-    get notebookViewModeChanged(): ISignal<this, NotebookDiffViewMode>;
+    /**
+     * Whether a rendered notebook view is currently available.
+     */
     get hasNotebookView(): boolean;
+    /**
+     * Set whether a rendered notebook view is available.
+     */
     setHasNotebookView(value: boolean): void;
+    /**
+     * A signal emitted when rendered-notebook availability changes.
+     */
     get hasNotebookViewChanged(): ISignal<this, boolean>;
-    get diffStyle(): DiffStyle;
-    setDiffStyle(style: DiffStyle): void;
-    get diffStyleChanged(): ISignal<this, DiffStyle>;
     /**
-     * Whether the Split/Unified toolbar selector currently applies.
+     * Whether the Split/Unified and line-wrap toolbar controls currently apply.
      */
     get fileDiffActive(): boolean;
+    /**
+     * Set whether the textual file diff is the active view.
+     */
     setFileDiffActive(value: boolean): void;
+    /**
+     * A signal emitted when {@link fileDiffActive} changes.
+     */
     get fileDiffActiveChanged(): ISignal<this, boolean>;
     /**
      * Emitted when a post-discard reload leaves the diff with no hunks.
      */
     get emptied(): ISignal<this, void>;
+    /**
+     * Emit the {@link emptied} signal.
+     */
     notifyEmptied(): void;
+    /**
+     * Resolve and clear the pending `refresh()` promise, if any.
+     */
     settleRefresh(): void;
+    /**
+     * Dispose of the resources held by the widget.
+     */
     dispose(): void;
+    /**
+     * A counter incremented on each `refresh()` to trigger a content re-fetch.
+     */
     get reloadNonce(): number;
+    /**
+     * The application-level services used by the rendered diff.
+     */
     get context(): IXtralabDiffContext;
+    /**
+     * Render the diff view for the current model.
+     */
     protected render(): React.ReactElement;
     private _model;
     private _context;
     private _reloadNonce;
     private _pendingRefresh;
-    private _notebookViewMode;
-    private _notebookViewModeChanged;
     private _hasNotebookView;
     private _hasNotebookViewChanged;
-    private _diffStyle;
-    private _diffStyleChanged;
     private _fileDiffActive;
     private _fileDiffActiveChanged;
     private _emptied;
@@ -97,6 +150,9 @@ export declare class XtralabDiffWidget extends ReactWidget implements Git.Diff.I
  * Structural toolbar type shared across host package boundaries.
  */
 interface IDiffToolbar {
+    /**
+     * Add an item to the toolbar under the given name.
+     */
     addItem(name: string, widget: Widget): boolean;
 }
 /**