jupyterlab_advanced_image_viewer_extension 0.4.7

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Stellars Henson
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,39 @@
+# jupyterlab_advanced_image_viewer_extension
+
+[![GitHub Actions](https://github.com/stellarshenson/jupyterlab_advanced_image_viewer_extension/actions/workflows/build.yml/badge.svg)](https://github.com/stellarshenson/jupyterlab_advanced_image_viewer_extension/actions/workflows/build.yml)
+[![npm version](https://img.shields.io/npm/v/jupyterlab_advanced_image_viewer_extension.svg)](https://www.npmjs.com/package/jupyterlab_advanced_image_viewer_extension)
+[![PyPI version](https://img.shields.io/pypi/v/jupyterlab-advanced-image-viewer-extension.svg)](https://pypi.org/project/jupyterlab-advanced-image-viewer-extension/)
+[![Total PyPI downloads](https://static.pepy.tech/badge/jupyterlab-advanced-image-viewer-extension)](https://pepy.tech/project/jupyterlab-advanced-image-viewer-extension)
+[![JupyterLab 4](https://img.shields.io/badge/JupyterLab-4-orange.svg)](https://jupyterlab.readthedocs.io/en/stable/)
+[![Brought To You By KOLOMOLO](https://img.shields.io/badge/Brought%20To%20You%20By-KOLOMOLO-00ffff?style=flat)](https://kolomolo.com)
+[![Donate PayPal](https://img.shields.io/badge/Donate-PayPal-blue?style=flat)](https://www.paypal.com/donate/?hosted_button_id=B4KPBJDLLXTSA)
+
+A JupyterLab 4 extension that makes the built-in image viewer interactive. Images open fitted to the panel just like the stock viewer, then you can zoom with the wheel, pan by dragging, and step through a folder of images with the arrow keys - all in a single viewer tab.
+
+## Features
+
+- **Fit to screen** - every image opens scaled to fit the panel (same result as the stock viewer), and reset returns to that fit
+- **Wheel zoom** - scroll to zoom in and out, anchored at the cursor; zoom out as far as you like
+- **Drag to pan** - hold and drag to move around a zoomed-in image
+- **Toolbar controls** - zoom in, zoom out, and reset-to-fit buttons on the viewer toolbar
+- **Arrow-key navigation** - Left and Right open the previous and next image in the same folder, advancing within one viewer instead of opening new tabs
+
+## Requirements
+
+- JupyterLab >= 4.0.0
+
+## Install
+
+To install the extension, execute:
+
+```bash
+pip install jupyterlab_advanced_image_viewer_extension
+```
+
+## Uninstall
+
+To remove the extension, execute:
+
+```bash
+pip uninstall jupyterlab_advanced_image_viewer_extension
+```

package/lib/controller.d.ts

@@ -0,0 +1,30 @@
+export declare class ViewerController {
+    private host;
+    private img;
+    private s;
+    private tx;
+    private ty;
+    private panning;
+    private start;
+    private zoomStep;
+    private ro;
+    private disposed;
+    constructor(host: HTMLElement, img: HTMLImageElement, zoomStep: number);
+    setZoomStep(zoomStep: number): void;
+    reset(): void;
+    private viewport;
+    private clampScale;
+    private zoomAt;
+    private onWheel;
+    zoomIn(): void;
+    zoomOut(): void;
+    private canPan;
+    private clampPan;
+    private onDown;
+    private onMove;
+    private onUp;
+    private onResize;
+    private updateCursor;
+    private apply;
+    dispose(): void;
+}

package/lib/controller.js

@@ -0,0 +1,137 @@
+// ViewerController adds zoom + pan ON TOP of JupyterLab's stock image viewer.
+// The stock viewer already fits the image with CSS (object-fit: contain,
+// max-width/height: 100%), so the identity transform IS the correct
+// fit-to-screen view for both raster and SVG. We never read naturalWidth /
+// naturalHeight (an SVG with only a viewBox reports a bogus intrinsic size).
+// Zoom is a single relative factor s (s = 1 is fit); pan is a translate.
+// transform-origin is the host centre, matching the centred object-fit layout.
+const MIN_SCALE = 0.05;
+const MAX_SCALE = 40;
+export class ViewerController {
+    constructor(host, img, zoomStep) {
+        this.s = 1;
+        this.tx = 0;
+        this.ty = 0;
+        this.panning = false;
+        this.start = { x: 0, y: 0, tx: 0, ty: 0 };
+        this.disposed = false;
+        this.onWheel = (e) => {
+            e.preventDefault();
+            const r = this.host.getBoundingClientRect();
+            const factor = e.deltaY < 0 ? 1 + this.zoomStep : 1 / (1 + this.zoomStep);
+            this.zoomAt(factor, e.clientX - r.left, e.clientY - r.top);
+        };
+        this.onDown = (e) => {
+            if (!this.canPan()) {
+                return;
+            }
+            e.preventDefault();
+            this.panning = true;
+            this.start = { x: e.clientX, y: e.clientY, tx: this.tx, ty: this.ty };
+            this.host.style.cursor = 'grabbing';
+            window.addEventListener('mousemove', this.onMove);
+            window.addEventListener('mouseup', this.onUp);
+        };
+        this.onMove = (e) => {
+            if (!this.panning) {
+                return;
+            }
+            this.tx = this.start.tx + (e.clientX - this.start.x);
+            this.ty = this.start.ty + (e.clientY - this.start.y);
+            this.clampPan();
+            this.apply();
+        };
+        this.onUp = () => {
+            this.panning = false;
+            this.updateCursor();
+            window.removeEventListener('mousemove', this.onMove);
+            window.removeEventListener('mouseup', this.onUp);
+        };
+        this.host = host;
+        this.img = img;
+        this.zoomStep = zoomStep;
+        this.host.style.overflow = 'hidden';
+        this.img.style.transformOrigin = 'center center';
+        this.host.addEventListener('wheel', this.onWheel, { passive: false });
+        this.host.addEventListener('mousedown', this.onDown);
+        this.ro = new ResizeObserver(() => this.onResize());
+        this.ro.observe(this.host);
+        this.apply();
+    }
+    setZoomStep(zoomStep) {
+        this.zoomStep = zoomStep;
+    }
+    reset() {
+        this.s = 1;
+        this.tx = 0;
+        this.ty = 0;
+        this.apply();
+    }
+    viewport() {
+        return { vw: this.host.clientWidth, vh: this.host.clientHeight };
+    }
+    clampScale(v) {
+        return Math.min(Math.max(v, MIN_SCALE), MAX_SCALE);
+    }
+    // Cursor-anchored zoom about the host centre. With transform
+    // M(p) = C + s*(p - C) + t, keeping the point under (ax, ay) fixed gives
+    // t' = a - C - (s'/s) * (a - C - t).
+    zoomAt(factor, ax, ay) {
+        const sNew = this.clampScale(this.s * factor);
+        if (sNew === this.s) {
+            return;
+        }
+        const { vw, vh } = this.viewport();
+        const cx = vw / 2;
+        const cy = vh / 2;
+        const k = sNew / this.s;
+        this.tx = ax - cx - k * (ax - cx - this.tx);
+        this.ty = ay - cy - k * (ay - cy - this.ty);
+        this.s = sNew;
+        this.clampPan();
+        this.apply();
+    }
+    zoomIn() {
+        const { vw, vh } = this.viewport();
+        this.zoomAt(1 + this.zoomStep, vw / 2, vh / 2);
+    }
+    zoomOut() {
+        const { vw, vh } = this.viewport();
+        this.zoomAt(1 / (1 + this.zoomStep), vw / 2, vh / 2);
+    }
+    canPan() {
+        return this.s > 1;
+    }
+    // Bound the translate to the overflow implied by the zoom so the image
+    // cannot be panned out of view. Range collapses to 0 as s approaches 1.
+    clampPan() {
+        const { vw, vh } = this.viewport();
+        const mx = (Math.max(this.s, 1) - 1) * vw * 0.5;
+        const my = (Math.max(this.s, 1) - 1) * vh * 0.5;
+        this.tx = Math.min(mx, Math.max(-mx, this.tx));
+        this.ty = Math.min(my, Math.max(-my, this.ty));
+    }
+    onResize() {
+        this.clampPan();
+        this.apply();
+    }
+    updateCursor() {
+        this.host.style.cursor = this.canPan() ? 'grab' : 'default';
+    }
+    apply() {
+        this.img.style.transformOrigin = 'center center';
+        this.img.style.transform = `translate(${this.tx}px, ${this.ty}px) scale(${this.s})`;
+        this.updateCursor();
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.ro.disconnect();
+        this.host.removeEventListener('wheel', this.onWheel);
+        this.host.removeEventListener('mousedown', this.onDown);
+        window.removeEventListener('mousemove', this.onMove);
+        window.removeEventListener('mouseup', this.onUp);
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/index.js

@@ -0,0 +1,203 @@
+import { ToolbarButton } from '@jupyterlab/apputils';
+import { PathExt } from '@jupyterlab/coreutils';
+import { IImageTracker } from '@jupyterlab/imageviewer';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { ViewerController } from './controller';
+const PLUGIN_ID = 'jupyterlab_advanced_image_viewer_extension:plugin';
+const CommandIDs = {
+    zoomIn: 'advanced-image-viewer:zoom-in',
+    zoomOut: 'advanced-image-viewer:zoom-out',
+    resetFit: 'advanced-image-viewer:reset-fit',
+    previous: 'advanced-image-viewer:previous-image',
+    next: 'advanced-image-viewer:next-image'
+};
+const IMAGE_EXTS = new Set([
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.bmp',
+    '.svg',
+    '.webp'
+]);
+const defaults = {
+    navEnabled: true,
+    zoomStep: 0.1
+};
+const plugin = {
+    id: PLUGIN_ID,
+    description: 'Advanced image viewer: cursor-anchored wheel zoom, drag-to-pan, fit-to-screen reset, and arrow-key folder navigation.',
+    autoStart: true,
+    requires: [IImageTracker],
+    optional: [ISettingRegistry],
+    activate: (app, tracker, settingRegistry) => {
+        console.log('JupyterLab extension jupyterlab_advanced_image_viewer_extension is activated!');
+        const controllers = new WeakMap();
+        const state = { ...defaults };
+        let keyBindings = [];
+        const currentController = () => {
+            var _a;
+            const widget = tracker.currentWidget;
+            if (!widget) {
+                return null;
+            }
+            return (_a = controllers.get(widget.content)) !== null && _a !== void 0 ? _a : null;
+        };
+        const attach = (widget) => {
+            const viewer = widget.content;
+            if (controllers.has(viewer)) {
+                return;
+            }
+            const host = viewer.node;
+            const img = host.querySelector('img');
+            if (!img) {
+                return;
+            }
+            const controller = new ViewerController(host, img, state.zoomStep);
+            controllers.set(viewer, controller);
+            widget.disposed.connect(() => {
+                controller.dispose();
+                controllers.delete(viewer);
+            });
+            widget.toolbar.addItem('advanced-zoom-out', new ToolbarButton({
+                label: '-',
+                tooltip: 'Zoom out',
+                onClick: () => app.commands.execute(CommandIDs.zoomOut)
+            }));
+            widget.toolbar.addItem('advanced-zoom-in', new ToolbarButton({
+                label: '+',
+                tooltip: 'Zoom in',
+                onClick: () => app.commands.execute(CommandIDs.zoomIn)
+            }));
+            widget.toolbar.addItem('advanced-reset-fit', new ToolbarButton({
+                label: 'Fit',
+                tooltip: 'Reset to fit',
+                onClick: () => app.commands.execute(CommandIDs.resetFit)
+            }));
+        };
+        tracker.forEach(widget => attach(widget));
+        tracker.widgetAdded.connect((_, widget) => attach(widget));
+        app.commands.addCommand(CommandIDs.zoomIn, {
+            label: 'Zoom In (Advanced Image Viewer)',
+            isEnabled: () => currentController() !== null,
+            execute: () => { var _a; return (_a = currentController()) === null || _a === void 0 ? void 0 : _a.zoomIn(); }
+        });
+        app.commands.addCommand(CommandIDs.zoomOut, {
+            label: 'Zoom Out (Advanced Image Viewer)',
+            isEnabled: () => currentController() !== null,
+            execute: () => { var _a; return (_a = currentController()) === null || _a === void 0 ? void 0 : _a.zoomOut(); }
+        });
+        app.commands.addCommand(CommandIDs.resetFit, {
+            label: 'Reset to Fit (Advanced Image Viewer)',
+            isEnabled: () => currentController() !== null,
+            execute: () => { var _a; return (_a = currentController()) === null || _a === void 0 ? void 0 : _a.reset(); }
+        });
+        const navigate = async (delta) => {
+            const widget = tracker.currentWidget;
+            if (!widget) {
+                return;
+            }
+            const path = widget.context.path;
+            const dirPath = PathExt.dirname(path);
+            const listing = await app.serviceManager.contents.get(dirPath, {
+                content: true
+            });
+            const content = listing.content;
+            if (!content) {
+                return;
+            }
+            const images = content
+                .filter(item => item.type === 'file' &&
+                IMAGE_EXTS.has(PathExt.extname(item.name).toLowerCase()))
+                .sort((a, b) => a.name.localeCompare(b.name, undefined, {
+                numeric: true,
+                sensitivity: 'base'
+            }));
+            if (images.length <= 1) {
+                return;
+            }
+            const idx = images.findIndex(item => item.path === path);
+            if (idx === -1) {
+                return;
+            }
+            const target = delta < 0 ? Math.max(0, idx - 1) : Math.min(images.length - 1, idx + 1);
+            if (target === idx) {
+                return;
+            }
+            // Advance within a single viewer: open the next image, then close the
+            // previous one. The stock image viewer binds each file to its own
+            // DocumentWidget, so an in-place file swap is not possible; opening and
+            // disposing the previous widget leaves one image tab that advances.
+            const previous = widget;
+            await app.commands.execute('docmanager:open', {
+                path: images[target].path,
+                factory: 'Image'
+            });
+            if (!previous.isDisposed && previous !== tracker.currentWidget) {
+                previous.dispose();
+            }
+        };
+        app.commands.addCommand(CommandIDs.previous, {
+            label: 'Previous Image In Folder',
+            isEnabled: () => state.navEnabled && tracker.currentWidget !== null,
+            execute: () => navigate(-1)
+        });
+        app.commands.addCommand(CommandIDs.next, {
+            label: 'Next Image In Folder',
+            isEnabled: () => state.navEnabled && tracker.currentWidget !== null,
+            execute: () => navigate(1)
+        });
+        const bindKeys = () => {
+            keyBindings.forEach(b => b.dispose());
+            keyBindings = [];
+            if (!state.navEnabled) {
+                return;
+            }
+            keyBindings.push(app.commands.addKeyBinding({
+                command: CommandIDs.previous,
+                keys: ['ArrowLeft'],
+                selector: '.jp-ImageViewer'
+            }));
+            keyBindings.push(app.commands.addKeyBinding({
+                command: CommandIDs.next,
+                keys: ['ArrowRight'],
+                selector: '.jp-ImageViewer'
+            }));
+        };
+        const applyState = () => {
+            tracker.forEach(widget => {
+                const controller = controllers.get(widget.content);
+                if (controller) {
+                    controller.setZoomStep(state.zoomStep);
+                }
+            });
+            bindKeys();
+        };
+        if (settingRegistry) {
+            settingRegistry
+                .load(PLUGIN_ID)
+                .then(settings => {
+                const read = () => {
+                    var _a, _b;
+                    const c = settings.composite;
+                    state.navEnabled = (_a = c.navEnabled) !== null && _a !== void 0 ? _a : defaults.navEnabled;
+                    state.zoomStep = (_b = c.zoomStep) !== null && _b !== void 0 ? _b : defaults.zoomStep;
+                };
+                read();
+                applyState();
+                settings.changed.connect(() => {
+                    read();
+                    applyState();
+                });
+            })
+                .catch(reason => {
+                console.error(`Failed to load settings for ${PLUGIN_ID}.`, reason);
+                applyState();
+            });
+        }
+        else {
+            applyState();
+        }
+    }
+};
+export default plugin;

package/package.json

@@ -0,0 +1,212 @@
+{
+    "name": "jupyterlab_advanced_image_viewer_extension",
+    "version": "0.4.7",
+    "description": "JupyterLab extension for advanced image viewing: fit-to-screen, cursor-anchored wheel zoom, drag-to-pan, and Left/Right arrow keys to move to the previous and next image in a folder",
+    "keywords": [
+        "jupyter",
+        "jupyterlab",
+        "jupyterlab-extension"
+    ],
+    "homepage": "https://github.com/stellarshenson/jupyterlab_advanced_image_viewer_extension",
+    "bugs": {
+        "url": "https://github.com/stellarshenson/jupyterlab_advanced_image_viewer_extension/issues"
+    },
+    "license": "BSD-3-Clause",
+    "author": {
+        "name": "Stellars Henson",
+        "email": "konrad.jelen+github@gmail.com"
+    },
+    "files": [
+        "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
+        "style/**/*.{css,js,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
+        "src/**/*.{ts,tsx}"
+    ],
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "style": "style/index.css",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/stellarshenson/jupyterlab_advanced_image_viewer_extension.git"
+    },
+    "scripts": {
+        "build": "jlpm build:lib && jlpm build:labextension:dev",
+        "build:prod": "jlpm clean && jlpm build:lib:prod && jlpm build:labextension",
+        "build:labextension": "jupyter labextension build .",
+        "build:labextension:dev": "jupyter labextension build --development True .",
+        "build:lib": "tsc --sourceMap",
+        "build:lib:prod": "tsc",
+        "clean": "jlpm clean:lib",
+        "clean:lib": "rimraf lib tsconfig.tsbuildinfo",
+        "clean:lintcache": "rimraf .eslintcache .stylelintcache",
+        "clean:labextension": "rimraf jupyterlab_advanced_image_viewer_extension/labextension jupyterlab_advanced_image_viewer_extension/_version.py",
+        "clean:all": "jlpm clean:lib && jlpm clean:labextension && jlpm clean:lintcache",
+        "eslint": "jlpm eslint:check --fix",
+        "eslint:check": "eslint . --cache --ext .ts,.tsx",
+        "install:extension": "jlpm build",
+        "lint": "jlpm stylelint && jlpm prettier && jlpm eslint",
+        "lint:check": "jlpm stylelint:check && jlpm prettier:check && jlpm eslint:check",
+        "prettier": "jlpm prettier:base --write --list-different",
+        "prettier:base": "prettier \"**/*{.ts,.tsx,.js,.jsx,.css,.json,.md}\"",
+        "prettier:check": "jlpm prettier:base --check",
+        "stylelint": "jlpm stylelint:check --fix",
+        "stylelint:check": "stylelint --cache \"style/**/*.css\"",
+        "test": "jest --coverage",
+        "watch": "run-p watch:src watch:labextension",
+        "watch:src": "tsc -w --sourceMap",
+        "watch:labextension": "jupyter labextension watch ."
+    },
+    "dependencies": {
+        "@jupyterlab/application": "^4.0.0",
+        "@jupyterlab/apputils": "^4.0.0",
+        "@jupyterlab/coreutils": "^6.0.0",
+        "@jupyterlab/docregistry": "^4.0.0",
+        "@jupyterlab/imageviewer": "^4.0.0",
+        "@jupyterlab/settingregistry": "^4.0.0",
+        "@lumino/disposable": "^2.0.0"
+    },
+    "devDependencies": {
+        "@jupyterlab/builder": "^4.0.0",
+        "@jupyterlab/testutils": "^4.0.0",
+        "@types/jest": "^29.2.0",
+        "@types/json-schema": "^7.0.11",
+        "@types/react": "^18.0.26",
+        "@types/react-addons-linked-state-mixin": "^0.14.22",
+        "@typescript-eslint/eslint-plugin": "^6.1.0",
+        "@typescript-eslint/parser": "^6.1.0",
+        "css-loader": "^6.7.1",
+        "eslint": "^8.36.0",
+        "eslint-config-prettier": "^8.8.0",
+        "eslint-plugin-prettier": "^5.0.0",
+        "jest": "^29.2.0",
+        "mkdirp": "^1.0.3",
+        "npm-run-all2": "^7.0.1",
+        "prettier": "^3.0.0",
+        "rimraf": "^5.0.1",
+        "source-map-loader": "^1.0.2",
+        "style-loader": "^3.3.1",
+        "stylelint": "^15.10.1",
+        "stylelint-config-recommended": "^13.0.0",
+        "stylelint-config-standard": "^34.0.0",
+        "stylelint-csstree-validator": "^3.0.0",
+        "stylelint-prettier": "^4.0.0",
+        "typescript": "~5.8.0",
+        "yjs": "^13.5.0"
+    },
+    "resolutions": {
+        "lib0": "0.2.111",
+        "webpack": "5.106.0",
+        "chalk": "4.1.2"
+    },
+    "overrides": {
+        "lib0": "0.2.111",
+        "webpack": "5.106.0",
+        "chalk": "4.1.2"
+    },
+    "sideEffects": [
+        "style/*.css",
+        "style/index.js"
+    ],
+    "styleModule": "style/index.js",
+    "publishConfig": {
+        "access": "public"
+    },
+    "jupyterlab": {
+        "extension": true,
+        "outputDir": "jupyterlab_advanced_image_viewer_extension/labextension",
+        "schemaDir": "schema"
+    },
+    "eslintIgnore": [
+        "node_modules",
+        "dist",
+        "coverage",
+        "**/*.d.ts",
+        "tests",
+        "**/__tests__",
+        "ui-tests"
+    ],
+    "eslintConfig": {
+        "extends": [
+            "eslint:recommended",
+            "plugin:@typescript-eslint/eslint-recommended",
+            "plugin:@typescript-eslint/recommended",
+            "plugin:prettier/recommended"
+        ],
+        "parser": "@typescript-eslint/parser",
+        "parserOptions": {
+            "project": "tsconfig.json",
+            "sourceType": "module"
+        },
+        "plugins": [
+            "@typescript-eslint"
+        ],
+        "rules": {
+            "@typescript-eslint/naming-convention": [
+                "error",
+                {
+                    "selector": "interface",
+                    "format": [
+                        "PascalCase"
+                    ],
+                    "custom": {
+                        "regex": "^I[A-Z]",
+                        "match": true
+                    }
+                }
+            ],
+            "@typescript-eslint/no-unused-vars": [
+                "warn",
+                {
+                    "args": "none"
+                }
+            ],
+            "@typescript-eslint/no-explicit-any": "off",
+            "@typescript-eslint/no-namespace": "off",
+            "@typescript-eslint/no-use-before-define": "off",
+            "@typescript-eslint/quotes": [
+                "error",
+                "single",
+                {
+                    "avoidEscape": true,
+                    "allowTemplateLiterals": false
+                }
+            ],
+            "curly": [
+                "error",
+                "all"
+            ],
+            "eqeqeq": "error",
+            "prefer-arrow-callback": "error"
+        }
+    },
+    "prettier": {
+        "singleQuote": true,
+        "trailingComma": "none",
+        "arrowParens": "avoid",
+        "endOfLine": "auto",
+        "overrides": [
+            {
+                "files": "package.json",
+                "options": {
+                    "tabWidth": 4
+                }
+            }
+        ]
+    },
+    "stylelint": {
+        "extends": [
+            "stylelint-config-recommended",
+            "stylelint-config-standard",
+            "stylelint-prettier/recommended"
+        ],
+        "plugins": [
+            "stylelint-csstree-validator"
+        ],
+        "rules": {
+            "csstree/validator": true,
+            "property-no-vendor-prefix": null,
+            "selector-class-pattern": "^([a-z][A-z\\d]*)(-[A-z\\d]+)*$",
+            "selector-no-vendor-prefix": null,
+            "value-no-vendor-prefix": null
+        }
+    }
+}

package/src/__tests__/jupyterlab_advanced_image_viewer_extension.spec.ts

@@ -0,0 +1,9 @@
+/**
+ * Example of [Jest](https://jestjs.io/docs/getting-started) unit tests
+ */
+
+describe('jupyterlab_advanced_image_viewer_extension', () => {
+  it('should be tested', () => {
+    expect(1 + 1).toEqual(2);
+  });
+});

package/src/controller.ts

@@ -0,0 +1,161 @@
+// ViewerController adds zoom + pan ON TOP of JupyterLab's stock image viewer.
+// The stock viewer already fits the image with CSS (object-fit: contain,
+// max-width/height: 100%), so the identity transform IS the correct
+// fit-to-screen view for both raster and SVG. We never read naturalWidth /
+// naturalHeight (an SVG with only a viewBox reports a bogus intrinsic size).
+// Zoom is a single relative factor s (s = 1 is fit); pan is a translate.
+// transform-origin is the host centre, matching the centred object-fit layout.
+
+const MIN_SCALE = 0.05;
+const MAX_SCALE = 40;
+
+export class ViewerController {
+  private host: HTMLElement;
+  private img: HTMLImageElement;
+  private s = 1;
+  private tx = 0;
+  private ty = 0;
+  private panning = false;
+  private start = { x: 0, y: 0, tx: 0, ty: 0 };
+  private zoomStep: number;
+  private ro: ResizeObserver;
+  private disposed = false;
+
+  constructor(host: HTMLElement, img: HTMLImageElement, zoomStep: number) {
+    this.host = host;
+    this.img = img;
+    this.zoomStep = zoomStep;
+    this.host.style.overflow = 'hidden';
+    this.img.style.transformOrigin = 'center center';
+    this.host.addEventListener('wheel', this.onWheel, { passive: false });
+    this.host.addEventListener('mousedown', this.onDown);
+    this.ro = new ResizeObserver(() => this.onResize());
+    this.ro.observe(this.host);
+    this.apply();
+  }
+
+  setZoomStep(zoomStep: number): void {
+    this.zoomStep = zoomStep;
+  }
+
+  reset(): void {
+    this.s = 1;
+    this.tx = 0;
+    this.ty = 0;
+    this.apply();
+  }
+
+  private viewport(): { vw: number; vh: number } {
+    return { vw: this.host.clientWidth, vh: this.host.clientHeight };
+  }
+
+  private clampScale(v: number): number {
+    return Math.min(Math.max(v, MIN_SCALE), MAX_SCALE);
+  }
+
+  // Cursor-anchored zoom about the host centre. With transform
+  // M(p) = C + s*(p - C) + t, keeping the point under (ax, ay) fixed gives
+  // t' = a - C - (s'/s) * (a - C - t).
+  private zoomAt(factor: number, ax: number, ay: number): void {
+    const sNew = this.clampScale(this.s * factor);
+    if (sNew === this.s) {
+      return;
+    }
+    const { vw, vh } = this.viewport();
+    const cx = vw / 2;
+    const cy = vh / 2;
+    const k = sNew / this.s;
+    this.tx = ax - cx - k * (ax - cx - this.tx);
+    this.ty = ay - cy - k * (ay - cy - this.ty);
+    this.s = sNew;
+    this.clampPan();
+    this.apply();
+  }
+
+  private onWheel = (e: WheelEvent): void => {
+    e.preventDefault();
+    const r = this.host.getBoundingClientRect();
+    const factor = e.deltaY < 0 ? 1 + this.zoomStep : 1 / (1 + this.zoomStep);
+    this.zoomAt(factor, e.clientX - r.left, e.clientY - r.top);
+  };
+
+  zoomIn(): void {
+    const { vw, vh } = this.viewport();
+    this.zoomAt(1 + this.zoomStep, vw / 2, vh / 2);
+  }
+
+  zoomOut(): void {
+    const { vw, vh } = this.viewport();
+    this.zoomAt(1 / (1 + this.zoomStep), vw / 2, vh / 2);
+  }
+
+  private canPan(): boolean {
+    return this.s > 1;
+  }
+
+  // Bound the translate to the overflow implied by the zoom so the image
+  // cannot be panned out of view. Range collapses to 0 as s approaches 1.
+  private clampPan(): void {
+    const { vw, vh } = this.viewport();
+    const mx = (Math.max(this.s, 1) - 1) * vw * 0.5;
+    const my = (Math.max(this.s, 1) - 1) * vh * 0.5;
+    this.tx = Math.min(mx, Math.max(-mx, this.tx));
+    this.ty = Math.min(my, Math.max(-my, this.ty));
+  }
+
+  private onDown = (e: MouseEvent): void => {
+    if (!this.canPan()) {
+      return;
+    }
+    e.preventDefault();
+    this.panning = true;
+    this.start = { x: e.clientX, y: e.clientY, tx: this.tx, ty: this.ty };
+    this.host.style.cursor = 'grabbing';
+    window.addEventListener('mousemove', this.onMove);
+    window.addEventListener('mouseup', this.onUp);
+  };
+
+  private onMove = (e: MouseEvent): void => {
+    if (!this.panning) {
+      return;
+    }
+    this.tx = this.start.tx + (e.clientX - this.start.x);
+    this.ty = this.start.ty + (e.clientY - this.start.y);
+    this.clampPan();
+    this.apply();
+  };
+
+  private onUp = (): void => {
+    this.panning = false;
+    this.updateCursor();
+    window.removeEventListener('mousemove', this.onMove);
+    window.removeEventListener('mouseup', this.onUp);
+  };
+
+  private onResize(): void {
+    this.clampPan();
+    this.apply();
+  }
+
+  private updateCursor(): void {
+    this.host.style.cursor = this.canPan() ? 'grab' : 'default';
+  }
+
+  private apply(): void {
+    this.img.style.transformOrigin = 'center center';
+    this.img.style.transform = `translate(${this.tx}px, ${this.ty}px) scale(${this.s})`;
+    this.updateCursor();
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.ro.disconnect();
+    this.host.removeEventListener('wheel', this.onWheel);
+    this.host.removeEventListener('mousedown', this.onDown);
+    window.removeEventListener('mousemove', this.onMove);
+    window.removeEventListener('mouseup', this.onUp);
+  }
+}

package/src/index.ts

@@ -0,0 +1,268 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+
+import { ToolbarButton } from '@jupyterlab/apputils';
+
+import { PathExt } from '@jupyterlab/coreutils';
+
+import { IDocumentWidget } from '@jupyterlab/docregistry';
+
+import { IImageTracker, ImageViewer } from '@jupyterlab/imageviewer';
+
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+
+import { IDisposable } from '@lumino/disposable';
+
+import { ViewerController } from './controller';
+
+const PLUGIN_ID = 'jupyterlab_advanced_image_viewer_extension:plugin';
+
+const CommandIDs = {
+  zoomIn: 'advanced-image-viewer:zoom-in',
+  zoomOut: 'advanced-image-viewer:zoom-out',
+  resetFit: 'advanced-image-viewer:reset-fit',
+  previous: 'advanced-image-viewer:previous-image',
+  next: 'advanced-image-viewer:next-image'
+};
+
+const IMAGE_EXTS = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.bmp',
+  '.svg',
+  '.webp'
+]);
+
+interface ISettingsState {
+  navEnabled: boolean;
+  zoomStep: number;
+}
+
+const defaults: ISettingsState = {
+  navEnabled: true,
+  zoomStep: 0.1
+};
+
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: PLUGIN_ID,
+  description:
+    'Advanced image viewer: cursor-anchored wheel zoom, drag-to-pan, fit-to-screen reset, and arrow-key folder navigation.',
+  autoStart: true,
+  requires: [IImageTracker],
+  optional: [ISettingRegistry],
+  activate: (
+    app: JupyterFrontEnd,
+    tracker: IImageTracker,
+    settingRegistry: ISettingRegistry | null
+  ): void => {
+    console.log(
+      'JupyterLab extension jupyterlab_advanced_image_viewer_extension is activated!'
+    );
+    const controllers = new WeakMap<ImageViewer, ViewerController>();
+    const state: ISettingsState = { ...defaults };
+    let keyBindings: IDisposable[] = [];
+
+    const currentController = (): ViewerController | null => {
+      const widget = tracker.currentWidget;
+      if (!widget) {
+        return null;
+      }
+      return controllers.get(widget.content) ?? null;
+    };
+
+    const attach = (widget: IDocumentWidget<ImageViewer>): void => {
+      const viewer = widget.content;
+      if (controllers.has(viewer)) {
+        return;
+      }
+      const host = viewer.node;
+      const img = host.querySelector('img');
+      if (!img) {
+        return;
+      }
+      const controller = new ViewerController(
+        host,
+        img as HTMLImageElement,
+        state.zoomStep
+      );
+      controllers.set(viewer, controller);
+      widget.disposed.connect(() => {
+        controller.dispose();
+        controllers.delete(viewer);
+      });
+
+      widget.toolbar.addItem(
+        'advanced-zoom-out',
+        new ToolbarButton({
+          label: '-',
+          tooltip: 'Zoom out',
+          onClick: () => app.commands.execute(CommandIDs.zoomOut)
+        })
+      );
+      widget.toolbar.addItem(
+        'advanced-zoom-in',
+        new ToolbarButton({
+          label: '+',
+          tooltip: 'Zoom in',
+          onClick: () => app.commands.execute(CommandIDs.zoomIn)
+        })
+      );
+      widget.toolbar.addItem(
+        'advanced-reset-fit',
+        new ToolbarButton({
+          label: 'Fit',
+          tooltip: 'Reset to fit',
+          onClick: () => app.commands.execute(CommandIDs.resetFit)
+        })
+      );
+    };
+
+    tracker.forEach(widget => attach(widget));
+    tracker.widgetAdded.connect((_, widget) => attach(widget));
+
+    app.commands.addCommand(CommandIDs.zoomIn, {
+      label: 'Zoom In (Advanced Image Viewer)',
+      isEnabled: () => currentController() !== null,
+      execute: () => currentController()?.zoomIn()
+    });
+    app.commands.addCommand(CommandIDs.zoomOut, {
+      label: 'Zoom Out (Advanced Image Viewer)',
+      isEnabled: () => currentController() !== null,
+      execute: () => currentController()?.zoomOut()
+    });
+    app.commands.addCommand(CommandIDs.resetFit, {
+      label: 'Reset to Fit (Advanced Image Viewer)',
+      isEnabled: () => currentController() !== null,
+      execute: () => currentController()?.reset()
+    });
+
+    const navigate = async (delta: number): Promise<void> => {
+      const widget = tracker.currentWidget;
+      if (!widget) {
+        return;
+      }
+      const path = widget.context.path;
+      const dirPath = PathExt.dirname(path);
+      const listing = await app.serviceManager.contents.get(dirPath, {
+        content: true
+      });
+      const content = listing.content as Array<{
+        name: string;
+        path: string;
+        type: string;
+      }> | null;
+      if (!content) {
+        return;
+      }
+      const images = content
+        .filter(
+          item =>
+            item.type === 'file' &&
+            IMAGE_EXTS.has(PathExt.extname(item.name).toLowerCase())
+        )
+        .sort((a, b) =>
+          a.name.localeCompare(b.name, undefined, {
+            numeric: true,
+            sensitivity: 'base'
+          })
+        );
+      if (images.length <= 1) {
+        return;
+      }
+      const idx = images.findIndex(item => item.path === path);
+      if (idx === -1) {
+        return;
+      }
+      const target =
+        delta < 0 ? Math.max(0, idx - 1) : Math.min(images.length - 1, idx + 1);
+      if (target === idx) {
+        return;
+      }
+      // Advance within a single viewer: open the next image, then close the
+      // previous one. The stock image viewer binds each file to its own
+      // DocumentWidget, so an in-place file swap is not possible; opening and
+      // disposing the previous widget leaves one image tab that advances.
+      const previous = widget;
+      await app.commands.execute('docmanager:open', {
+        path: images[target].path,
+        factory: 'Image'
+      });
+      if (!previous.isDisposed && previous !== tracker.currentWidget) {
+        previous.dispose();
+      }
+    };
+
+    app.commands.addCommand(CommandIDs.previous, {
+      label: 'Previous Image In Folder',
+      isEnabled: () => state.navEnabled && tracker.currentWidget !== null,
+      execute: () => navigate(-1)
+    });
+    app.commands.addCommand(CommandIDs.next, {
+      label: 'Next Image In Folder',
+      isEnabled: () => state.navEnabled && tracker.currentWidget !== null,
+      execute: () => navigate(1)
+    });
+
+    const bindKeys = (): void => {
+      keyBindings.forEach(b => b.dispose());
+      keyBindings = [];
+      if (!state.navEnabled) {
+        return;
+      }
+      keyBindings.push(
+        app.commands.addKeyBinding({
+          command: CommandIDs.previous,
+          keys: ['ArrowLeft'],
+          selector: '.jp-ImageViewer'
+        })
+      );
+      keyBindings.push(
+        app.commands.addKeyBinding({
+          command: CommandIDs.next,
+          keys: ['ArrowRight'],
+          selector: '.jp-ImageViewer'
+        })
+      );
+    };
+
+    const applyState = (): void => {
+      tracker.forEach(widget => {
+        const controller = controllers.get(widget.content);
+        if (controller) {
+          controller.setZoomStep(state.zoomStep);
+        }
+      });
+      bindKeys();
+    };
+
+    if (settingRegistry) {
+      settingRegistry
+        .load(PLUGIN_ID)
+        .then(settings => {
+          const read = (): void => {
+            const c = settings.composite as Partial<ISettingsState>;
+            state.navEnabled = c.navEnabled ?? defaults.navEnabled;
+            state.zoomStep = c.zoomStep ?? defaults.zoomStep;
+          };
+          read();
+          applyState();
+          settings.changed.connect(() => {
+            read();
+            applyState();
+          });
+        })
+        .catch(reason => {
+          console.error(`Failed to load settings for ${PLUGIN_ID}.`, reason);
+          applyState();
+        });
+    } else {
+      applyState();
+    }
+  }
+};
+
+export default plugin;

package/style/base.css

@@ -0,0 +1,5 @@
+/*
+    See the JupyterLab Developer Guide for useful CSS Patterns:
+
+    https://jupyterlab.readthedocs.io/en/stable/developer/css.html
+*/

package/style/index.css

@@ -0,0 +1 @@
+@import url('base.css');

package/style/index.js

@@ -0,0 +1 @@
+import './base.css';