@computationalpathologygroup/openslide-js 1.0.0-beta.2

package/NOTICE

@@ -0,0 +1,216 @@
+openslide-js
+
+This product is distributed under the GNU Lesser General Public License,
+version 2.1 only (LGPL-2.1-only). See the LICENSE file in the repository
+root for the full license text.
+
+This product bundles and is built from several third-party components,
+each carrying its own license. The notices below identify those
+components, their upstream sources, and the licenses under which they
+are distributed.
+
+================================================================================
+1. Bundled into wasm/dist/openslide.wasm
+================================================================================
+
+The compiled WebAssembly artifact wasm/dist/openslide.wasm statically
+links the following projects. Each retains its own license; the
+combined binary is distributed under LGPL-2.1-only (the strongest
+copyleft of any bundled component).
+
+  OpenSlide
+    Upstream:  https://openslide.org
+               https://github.com/openslide/openslide
+    Pin:       v4.0.0 tagged release (matches the official binary
+               distribution openslide-bin v4.0.0.13)
+    License:   LGPL-2.1-only
+    Note:      Modified via wasm/patches/openslide.patch — eight small
+               mechanical _with_data thunk wrappers for GLib sort
+               callbacks under Emscripten's strict call_indirect type
+               check. The complete corresponding source, including the
+               patch and the fetch script that pins the upstream tag,
+               is available in the wasm/ directory of this repository.
+               Also: wasm/dependencies/fetch-openslide.sh removes
+               subdir('tools') from upstream meson.build via sed
+               (Emscripten cannot link native helper executables).
+
+  GLib
+    Upstream:  https://gitlab.gnome.org/GNOME/glib
+    Pin:       2.88.1
+    License:   LGPL-2.1-or-later
+    Note:      Modified via wasm/patches/glib.patch (10-patch mailbox
+               series from wasm-vips by Kleis Auke Wolthuizen, see
+               Section 3).
+
+  Cairo
+    Upstream:  https://gitlab.freedesktop.org/cairo/cairo
+    Pin:       1.18.4
+    License:   LGPL-2.1-only OR MPL-1.1
+    Note:      Unmodified upstream source.
+
+  gdk-pixbuf
+    Upstream:  https://gitlab.gnome.org/GNOME/gdk-pixbuf
+    Pin:       2.42.12
+    License:   LGPL-2.1-or-later
+    Note:      Modified via wasm/patches/gdk-pixbuf.patch — ~9 lines
+               wrapping the gdkpixbuf_bin executables foreach in
+               `if not meson.is_cross_build()`. Strategy informed by
+               discere-os/gdk-pixbuf.wasm (see Section 3).
+
+  fontconfig
+    Upstream:  https://gitlab.freedesktop.org/fontconfig/fontconfig
+    Pin:       2.17.1
+    License:   MIT (HPND-style)
+    Note:      Unmodified upstream source. Upstream commit e3563fa2
+               (May 2023) migrated src/meson.build to meson's built-in
+               cc.preprocess(), making it Emscripten-buildable without
+               any compiler-detection patch.
+
+  pixman
+    Upstream:  https://gitlab.freedesktop.org/pixman/pixman
+    License:   MIT
+
+  FreeType
+    Upstream:  https://freetype.org
+    License:   FTL OR GPL-2.0-or-later
+
+  libtiff
+    Upstream:  https://gitlab.com/libtiff/libtiff
+    License:   libtiff (BSD-style)
+
+  libjpeg-turbo
+    Upstream:  https://libjpeg-turbo.org
+    License:   IJG AND BSD-3-Clause AND Zlib
+
+  OpenJPEG
+    Upstream:  https://www.openjpeg.org
+    License:   BSD-2-Clause
+
+  libpng
+    Upstream:  http://www.libpng.org/pub/png/libpng.html
+    License:   libpng-2.0
+
+  libxml2
+    Upstream:  https://gitlab.gnome.org/GNOME/libxml2
+    License:   MIT
+
+  Expat (libexpat)
+    Upstream:  https://libexpat.github.io
+    License:   MIT
+
+  zlib
+    Upstream:  https://www.zlib.net
+    License:   Zlib
+
+  zstd
+    Upstream:  https://github.com/facebook/zstd
+    License:   BSD-3-Clause OR GPL-2.0-only
+
+  libffi
+    Upstream:  https://github.com/libffi/libffi
+    License:   MIT
+
+  SQLite
+    Upstream:  https://www.sqlite.org
+    License:   blessing (public-domain dedication)
+
+================================================================================
+2. Source availability (LGPL-2.1 §6)
+================================================================================
+
+The LGPL-2.1-licensed components above (notably OpenSlide, GLib, Cairo,
+and gdk-pixbuf) require that the complete corresponding source of the
+combined work be available to recipients.
+
+The complete corresponding source is the contents of the openslide-js
+repository at https://github.com/computationalpathologygroup/openslide-js,
+specifically the wasm/ directory, which contains:
+
+  - Dockerfile + build.sh — the deterministic build pipeline
+  - dependencies/fetch-*.sh — one fetch script per bundled project,
+    pinning the exact upstream commit/release used
+  - patches/*.patch — every modification applied to upstream sources
+  - openslide-api.c + emscripten-crossfile.meson — the linker glue
+    and Emscripten cross-compilation configuration
+
+Reproducing the bundled wasm binary from these sources requires Docker
+and is documented in README.md under "Building the WASM module".
+
+================================================================================
+3. Build infrastructure attribution
+================================================================================
+
+The WebAssembly build pipeline under wasm/ incorporates work from the
+following upstream projects. Both are MIT-licensed and compatible with
+openslide-js's LGPL-2.1-only distribution.
+
+  @conflux-xyz/openslide-wasm
+    Upstream:  https://github.com/conflux-xyz/openslide-wasm
+               https://www.npmjs.com/package/@conflux-xyz/openslide-wasm
+    License:   MIT (declared in the package's npm package.json; the
+               upstream GitHub repository does not currently carry an
+               explicit LICENSE file)
+    Used for:  The overall WASM build pipeline — the Emscripten base
+               image and required packages, the meson and
+               cmake flag sets for each bundled native library, and
+               the emscripten meson cross-file. No source patches to
+               bundled libraries are derived from this project; 
+               all four originally-imported patches (cairo,
+               fontconfig, gdk-pixbuf, openslide) have meson options, 
+               upstream version upgrades, single-line sed transforms 
+               in the fetch scripts, code informed by other projects 
+               (see entries below).
+
+  wasm-vips (by Kleis Auke Wolthuizen)
+    Upstream:  https://github.com/kleisauke/wasm-vips
+    License:   MIT
+    Used for:  The GLib WebAssembly patch series carried in
+               wasm/patches/glib.patch. Per-patch author lines are
+               preserved in the patch's mailbox-format headers.
+
+  VitoVan/pango-cairo-wasm (by Vito Van)
+    Upstream:  https://github.com/VitoVan/pango-cairo-wasm
+    License:   WTFPL (Do What The Fuck You Want To Public License)
+    Used for:  The strategic insight that cairo can be cross-built for
+               WebAssembly with no source patches: cairo's util/
+               meson.build gates each helper executable
+               (cairo-gobject, cairo-script, cairo-trace, cairo-fdr) on
+               feature_conf flags, and the top-level executable loop
+               iterates an empty list when gtk_dep is not found. With
+               openslide-js's dependency set, none of those targets are
+               triggered, so the previous wasm/patches/cairo.patch
+               (which removed `subdir('util')`) is unnecessary.
+
+  discere-os/gdk-pixbuf.wasm and discere-os/fontconfig.wasm
+    (by Isaac Johnston / Superstruct Ltd)
+    Upstream:  https://github.com/discere-os/gdk-pixbuf.wasm
+               https://github.com/discere-os/fontconfig.wasm
+    License:   LGPL-2.1-or-later (gdk-pixbuf.wasm, matching upstream);
+               upstream fontconfig license + MIT build infrastructure
+               (fontconfig.wasm)
+    Used for:  (1) For gdk-pixbuf — the strategy to cross-build cleanly
+               under Emscripten without source patches to the C loader
+               code: relying on the pre-existing upstream gating of
+               USE_GMODULE on GLib's pkg-config-advertised
+               `gmodule_supported` value, and the `builtin_loaders=all`
+               meson option for the loader-plugin loop. The thin patch
+               at wasm/patches/gdk-pixbuf.patch (only gating helper
+               executables on `meson.is_cross_build()`) is original
+               openslide-js code.
+               (2) For fontconfig — the strategy of pinning fontconfig
+               2.17.1 (which contains upstream commit e3563fa2,
+               May 2023, migrating src/meson.build to meson's built-in
+               cc.preprocess()), eliminating the conflux-xyz-derived
+               `cc.get_id() == 'clang' or ...emscripten` workaround
+               entirely. No patch is needed at fontconfig 2.17.1+.
+
+The Emscripten C glue at wasm/openslide-api.c is distributed under 
+LGPL-2.1-only because it links directly against OpenSlide.
+
+================================================================================
+4. No warranty
+================================================================================
+
+This software is provided "as is", without warranty of any kind,
+express or implied. See the LICENSE file for the full LGPL-2.1-only
+disclaimer of warranty.

package/README.md

@@ -0,0 +1,160 @@
+# openslide-js
+
+Client-side whole-slide image library powered by [OpenSlide](https://openslide.org) and WebAssembly.
+
+Runs entirely in the browser — no server required.
+
+> For native (Linux / Windows / macOS) usage, see [openslide-bin](https://github.com/openslide/openslide-bin) — the OpenSlide team's official binary distribution of the same C library used by openslide-python, openslide-java, and other native consumers. openslide-js is the WebAssembly sibling: same upstream OpenSlide and dependency pins (v4.0.0, GLib 2.88.1, Cairo 1.18.4, libdicom 1.0.5, etc.) compiled for the browser via Emscripten, with a TypeScript wrapper API on top.
+
+## Install
+
+```bash
+npm install @computationalpathologygroup/openslide-js
+```
+
+## Usage
+
+```typescript
+import { OpenSlide } from '@computationalpathologygroup/openslide-js';
+
+const openslide = await OpenSlide.initialize();
+const slide = await openslide.open(file); // File | File[] | URL | string
+
+console.log(slide.levelCount);
+console.log(slide.properties);
+
+const imageData = await slide.readRegion(x, y, level, width, height);
+slide.close();
+```
+
+### Multi-file formats (MIRAX, VMS)
+
+```typescript
+import { OpenSlide, type VirtualFile } from '@computationalpathologygroup/openslide-js';
+
+const entries: VirtualFile[] = [
+  { path: 'slide.mrxs', file: mrxsFile },
+  { path: 'slide/Slidedat.ini', file: datFile },
+  // ... remaining files
+];
+
+const slide = await openslide.open(entries);
+```
+
+### Deep Zoom
+
+Slides are read sparsely — only the byte ranges needed to decode the requested Deep Zoom tiles are accessed, via HTTP range requests for URLs (the origin must serve `Accept-Ranges: bytes`) or via the browser's File API for local files — so multi-gigabyte whole-slide images can be browsed in the viewport without ever loading the full file into memory.
+
+```typescript
+import { DeepZoomGenerator } from '@computationalpathologygroup/openslide-js';
+
+const dz = new DeepZoomGenerator(slide);
+const tile = await dz.getTile(level, col, row);  // returns ImageData
+const xml = dz.getDzi('jpeg');
+```
+
+## Format Support
+
+openslide-js supports the same whole-slide image formats as [OpenSlide](https://openslide.org), running entirely client-side via WebAssembly. Some formats have limitations in the browser environment.
+
+### Single-File Formats
+
+| Vendor | Format | Extension | Compression | Support level |
+|:-------|:-------|:----------|:------------|:------:|
+| Aperio | SVS | `.svs` | JPEG | :white_check_mark: Full |
+| Aperio | SVS | `.svs` | JPEG 2000 | :white_check_mark: Full |
+| Generic | Tiled TIFF | `.tiff` | Mixed | :white_check_mark: Full |
+| Hamamatsu | NDPI | `.ndpi` | JPEG | :white_check_mark: Full |
+| Leica | SCN (brightfield) | `.scn` | JPEG | :white_check_mark: Full |
+| Philips | TIFF | `.tiff` | JPEG | :white_check_mark: Full |
+
+### Multi-File Formats
+
+| Vendor | Format | Extension | Support level | Notes |
+|:-------|:-------|:----------|:------:|:------|
+| DICOM | WSI | `.dcm` | :white_check_mark: Full | Opened via `VirtualFile[]` directory mounting |
+| Hamamatsu | VMS | `.vms` | :white_check_mark: Full | Opened via `VirtualFile[]` directory mounting |
+| Mirax | MRXS | `.mrxs` | :white_check_mark: Full | Opened via `VirtualFile[]` directory mounting |
+| Trestle | TIF | `.tif` | :white_check_mark: Full | Opened via `VirtualFile[]` directory mounting |
+
+### Unsupported
+
+| Vendor | Format | Extension | Support level | Limitation |
+|:-------|:-------|:----------|:------:|:-----------|
+| Leica | SCN (fluorescence) | `.scn` | :x: No | No main brightfield image in fluorescence-only files |
+| Olympus | VSI | `.vsi` | :x: No | VSI opener cannot find companion ETS directory via WORKERFS |
+| Ventana | BIF | `.bif` | :x: No | `LEFT` direction attribute not supported |
+| Zeiss | CZI | `.czi` | :x: No | Vendor detection not in OpenSlide v4.0.0 (added upstream post-release); JPEG XR codec also not compiled |
+| Zeiss | ZVI | `.zvi` | :x: No | OLE2 compound documents cannot be read via HTTP |
+
+### Not Yet Tested
+
+| Vendor | Format | Extension | Support level | Notes |
+|:-------|:-------|:----------|:------|
+| Sakura | SVSLIDE | `.svslide` | SQLite-based, needs filesystem access |
+
+> **Test coverage:** 292 integration tests across 15 formats (10 single-file + 5 multi-file), running in headless Chromium via Playwright.
+> Run locally with `npm run test:integration` or containerized with `npm run test:integration:docker`.
+
+## Requirements
+
+The WASM module uses `SharedArrayBuffer` and requires the following HTTP headers:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+## Building the WASM module
+
+Requires Docker.
+
+```bash
+docker build -t openslide-js ./wasm
+mkdir -p wasm/dist
+docker run --rm -v "$(pwd)/wasm/dist:/output" openslide-js
+```
+
+Output: `wasm/dist/openslide.js` and `wasm/dist/openslide.wasm`.
+
+## Building the TypeScript layer
+
+```bash
+npm run build:ts
+```
+
+## Test Data
+
+Integration tests require whole-slide image files that are not bundled in this repository (they are git-ignored). Download them with:
+
+```bash
+npm run test:integration:fixtures
+```
+
+This runs `test/integration/download-fixtures.mjs`, which:
+
+1. Fetches the [upstream index.json](https://openslide.cs.cmu.edu/download/openslide-testdata/index.json) and updates the local `test/data/index.json` if it has changed.
+2. Downloads every file listed in the index into `test/data/`, preserving the subdirectory layout.
+3. Verifies each file's SHA-256 hash. Files already present with a matching hash are skipped.
+4. Extracts ZIP archives (multi-file formats) into sibling directories.
+
+Re-running the script is safe and idempotent — only missing or stale files are re-downloaded. The total download size is roughly 20 GiB for the full index.
+
+## Acknowledgements
+
+The WASM build pipeline under `wasm/` incorporates work from two upstream projects, both MIT-licensed:
+
+- [wasm-vips](https://github.com/kleisauke/wasm-vips) by Kleis Auke Wolthuizen (MIT) — the GLib WebAssembly patch series in `wasm/patches/glib.patch` (per-patch author lines preserved in the mailbox headers).
+- [@conflux-xyz/openslide-wasm](https://github.com/conflux-xyz/openslide-wasm) (MIT, per its npm package) — informed the build strategy
+- [discere-os/gdk-pixbuf.wasm](https://github.com/discere-os/gdk-pixbuf.wasm) and [discere-os/fontconfig.wasm](https://github.com/discere-os/fontconfig.wasm) by Isaac Johnston — informed (a) the patch-light gdk-pixbuf cross-build strategy (lean on upstream's conditional `USE_GMODULE` gating + `-Dbuiltin_loaders=all` rather than stripping C code) and (b) the choice to pin fontconfig at 2.17.1, where upstream's `cc.preprocess()` migration (May 2023) eliminates the need for any compiler-detection patch.
+- [VitoVan/pango-cairo-wasm](https://github.com/VitoVan/pango-cairo-wasm) by Vito Van (WTFPL) — demonstrated that cairo cross-builds cleanly under Emscripten without any source patches; its meson invocation strategy informed dropping `wasm/patches/cairo.patch` entirely.
+
+See [NOTICE](NOTICE) for the full third-party attribution, including every component statically linked into `wasm/dist/openslide.wasm` and LGPL-2.1 §6 source-availability information.
+
+## Contributing
+
+Patches welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first — it documents how openslide-js handles third-party code, the preferred order of fixes (upstream meson option → sed transform → minimal patch), and the attribution rules that keep the project legally clean.
+
+## License
+
+LGPL-2.1-only — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/dist/cjs/deep-zoom.d.ts

@@ -0,0 +1,66 @@
+/**
+ * deep-zoom.ts
+ *
+ * Deep Zoom Image (DZI) tile generator. Maps DZI tile coordinates to
+ * OpenSlide region reads. Compatible with viewers like OpenSeadragon.
+ *
+ * Pure TypeScript — no WASM dependency. Operates on a Slide instance.
+ */
+import type { Dimensions, DziInfo } from './types.js';
+import type { Slide } from './slide.js';
+export interface DeepZoomOptions {
+    /** Tile size in pixels (not counting overlap). Default: 254. */
+    tileSize?: number;
+    /** Overlap in pixels on each edge. Default: 1. */
+    overlap?: number;
+    /** Only render the non-empty region defined by bounds properties. Default: false. */
+    limitBounds?: boolean;
+}
+export declare class DeepZoomGenerator {
+    private slide;
+    private _tileSize;
+    private _overlap;
+    private _levelCount;
+    private _levelDimensions;
+    private _levelTiles;
+    private _tileCount;
+    private _l0Offset;
+    private _l0Size;
+    constructor(slide: Slide, options?: DeepZoomOptions);
+    /** Number of Deep Zoom levels (0 = smallest, last = full resolution). */
+    get levelCount(): number;
+    /** Total number of tiles across all levels. */
+    get tileCount(): number;
+    /** Pixel dimensions at each DZI level. */
+    get levelDimensions(): readonly Dimensions[];
+    /** Tile grid dimensions at each DZI level. */
+    get levelTiles(): readonly {
+        columns: number;
+        rows: number;
+    }[];
+    /**
+     * Get a single tile as ImageData.
+     *
+     * @param level - DZI level (0 = smallest).
+     * @param col - Column index.
+     * @param row - Row index.
+     */
+    getTile(level: number, col: number, row: number): Promise<ImageData>;
+    /**
+     * Generate the DZI XML descriptor string.
+     */
+    getDzi(format?: 'jpeg' | 'png'): string;
+    /** Structured DZI info (alternative to XML). */
+    getDziInfo(format?: 'jpeg' | 'png'): DziInfo;
+    /**
+     * Compute tile bounds within the DZI level coordinate space.
+     */
+    private getTileInfo;
+    /**
+     * Downsample a tile to the target dimensions using nearest-neighbor.
+     * This is a fallback; for better quality, users should use createImageBitmap
+     * in their viewer integration.
+     */
+    private resampleTile;
+}
+//# sourceMappingURL=deep-zoom.d.ts.map

package/dist/cjs/deep-zoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-zoom.d.ts","sourceRoot":"","sources":["../../src/deep-zoom.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAe;IACvC,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,OAAO,CAA2B;gBAE9B,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,eAAe;IA8CnD,yEAAyE;IACzE,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,+CAA+C;IAC/C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,0CAA0C;IAC1C,IAAI,eAAe,IAAI,SAAS,UAAU,EAAE,CAE3C;IAED,8CAA8C;IAC9C,IAAI,UAAU,IAAI,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAE7D;IAED;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IA2C1E;;OAEG;IACH,MAAM,CAAC,MAAM,GAAE,MAAM,GAAG,KAAc,GAAG,MAAM;IAa/C,gDAAgD;IAChD,UAAU,CAAC,MAAM,GAAE,MAAM,GAAG,KAAc,GAAG,OAAO;IAapD;;OAEG;IACH,OAAO,CAAC,WAAW;IAgBnB;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAwBrB"}

package/dist/cjs/deep-zoom.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * deep-zoom.ts
+ *
+ * Deep Zoom Image (DZI) tile generator. Maps DZI tile coordinates to
+ * OpenSlide region reads. Compatible with viewers like OpenSeadragon.
+ *
+ * Pure TypeScript — no WASM dependency. Operates on a Slide instance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeepZoomGenerator = void 0;
+class DeepZoomGenerator {
+    slide;
+    _tileSize;
+    _overlap;
+    // Precomputed geometry
+    _levelCount;
+    _levelDimensions;
+    _levelTiles;
+    _tileCount;
+    // Slide region to render
+    _l0Offset;
+    _l0Size;
+    constructor(slide, options) {
+        this.slide = slide;
+        this._tileSize = options?.tileSize ?? 254;
+        this._overlap = options?.overlap ?? 1;
+        // Determine bounds
+        const props = slide.properties;
+        const limitBounds = options?.limitBounds ?? false;
+        if (limitBounds && props.has('openslide.bounds-x')) {
+            this._l0Offset = {
+                x: parseInt(props.get('openslide.bounds-x'), 10),
+                y: parseInt(props.get('openslide.bounds-y'), 10),
+            };
+            this._l0Size = {
+                w: parseInt(props.get('openslide.bounds-width'), 10),
+                h: parseInt(props.get('openslide.bounds-height'), 10),
+            };
+        }
+        else {
+            this._l0Offset = { x: 0, y: 0 };
+            this._l0Size = { w: slide.dimensions.width, h: slide.dimensions.height };
+        }
+        // Build the DZI level pyramid.
+        // DZI level 0 is the smallest (1x1), last level is full resolution.
+        const baseW = this._l0Size.w;
+        const baseH = this._l0Size.h;
+        this._levelCount = Math.ceil(Math.log2(Math.max(baseW, baseH))) + 1;
+        this._levelDimensions = [];
+        this._levelTiles = [];
+        this._tileCount = 0;
+        for (let i = 0; i < this._levelCount; i++) {
+            const scale = Math.pow(2, this._levelCount - 1 - i);
+            const w = Math.max(1, Math.ceil(baseW / scale));
+            const h = Math.max(1, Math.ceil(baseH / scale));
+            this._levelDimensions.push({ width: w, height: h });
+            const cols = Math.ceil(w / this._tileSize);
+            const rows = Math.ceil(h / this._tileSize);
+            this._levelTiles.push({ columns: cols, rows: rows });
+            this._tileCount += cols * rows;
+        }
+    }
+    /** Number of Deep Zoom levels (0 = smallest, last = full resolution). */
+    get levelCount() {
+        return this._levelCount;
+    }
+    /** Total number of tiles across all levels. */
+    get tileCount() {
+        return this._tileCount;
+    }
+    /** Pixel dimensions at each DZI level. */
+    get levelDimensions() {
+        return this._levelDimensions;
+    }
+    /** Tile grid dimensions at each DZI level. */
+    get levelTiles() {
+        return this._levelTiles;
+    }
+    /**
+     * Get a single tile as ImageData.
+     *
+     * @param level - DZI level (0 = smallest).
+     * @param col - Column index.
+     * @param row - Row index.
+     */
+    async getTile(level, col, row) {
+        if (level < 0 || level >= this._levelCount) {
+            throw new RangeError(`Level ${level} out of range [0, ${this._levelCount})`);
+        }
+        const grid = this._levelTiles[level];
+        if (col < 0 || col >= grid.columns || row < 0 || row >= grid.rows) {
+            throw new RangeError(`Tile (${col}, ${row}) out of range for level ${level}`);
+        }
+        const info = this.getTileInfo(level, col, row);
+        // Read from the slide at the best matching OpenSlide level
+        const dziDim = this._levelDimensions[level];
+        const downsample = this._l0Size.w / dziDim.width;
+        const slideLevel = this.slide.getBestLevelForDownsample(downsample);
+        const slideLevelDs = this.slide.levelDownsamples[slideLevel];
+        // Convert DZI tile coords to OpenSlide level-0 coords
+        const l0X = this._l0Offset.x + info.x * downsample;
+        const l0Y = this._l0Offset.y + info.y * downsample;
+        // Size to read at the slide level
+        const readW = Math.ceil(info.w * downsample / slideLevelDs);
+        const readH = Math.ceil(info.h * downsample / slideLevelDs);
+        const tile = await this.slide.readRegion(Math.round(l0X), Math.round(l0Y), slideLevel, readW, readH);
+        // If the read size matches the desired tile size, return directly
+        if (readW === info.w && readH === info.h) {
+            return tile;
+        }
+        // Otherwise, scale down to the exact tile dimensions using canvas
+        // (in a worker context, OffscreenCanvas; in main thread, regular canvas)
+        return this.resampleTile(tile, info.w, info.h);
+    }
+    /**
+     * Generate the DZI XML descriptor string.
+     */
+    getDzi(format = 'jpeg') {
+        const dim = this._levelDimensions[this._levelCount - 1];
+        return [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            `<Image xmlns="http://schemas.microsoft.com/deepzoom/2008"`,
+            `  TileSize="${this._tileSize}"`,
+            `  Overlap="${this._overlap}"`,
+            `  Format="${format}">`,
+            `  <Size Width="${dim.width}" Height="${dim.height}"/>`,
+            `</Image>`,
+        ].join('\n');
+    }
+    /** Structured DZI info (alternative to XML). */
+    getDziInfo(format = 'jpeg') {
+        const dim = this._levelDimensions[this._levelCount - 1];
+        return {
+            tileSize: this._tileSize,
+            overlap: this._overlap,
+            format,
+            width: dim.width,
+            height: dim.height,
+        };
+    }
+    // --- Internal ---
+    /**
+     * Compute tile bounds within the DZI level coordinate space.
+     */
+    getTileInfo(level, col, row) {
+        const dim = this._levelDimensions[level];
+        const ts = this._tileSize;
+        const ol = this._overlap;
+        // Tile origin (accounting for overlap on non-edge tiles)
+        const x = col === 0 ? 0 : col * ts - ol;
+        const y = row === 0 ? 0 : row * ts - ol;
+        // Tile extent
+        const x2 = Math.min((col + 1) * ts + ol, dim.width);
+        const y2 = Math.min((row + 1) * ts + ol, dim.height);
+        return { x, y, w: x2 - x, h: y2 - y };
+    }
+    /**
+     * Downsample a tile to the target dimensions using nearest-neighbor.
+     * This is a fallback; for better quality, users should use createImageBitmap
+     * in their viewer integration.
+     */
+    resampleTile(source, dstW, dstH) {
+        const srcW = source.width;
+        const srcH = source.height;
+        const src = source.data;
+        const dst = new Uint8ClampedArray(dstW * dstH * 4);
+        const xRatio = srcW / dstW;
+        const yRatio = srcH / dstH;
+        for (let dy = 0; dy < dstH; dy++) {
+            const sy = Math.min(Math.floor(dy * yRatio), srcH - 1);
+            for (let dx = 0; dx < dstW; dx++) {
+                const sx = Math.min(Math.floor(dx * xRatio), srcW - 1);
+                const si = (sy * srcW + sx) * 4;
+                const di = (dy * dstW + dx) * 4;
+                dst[di] = src[si];
+                dst[di + 1] = src[si + 1];
+                dst[di + 2] = src[si + 2];
+                dst[di + 3] = src[si + 3];
+            }
+        }
+        return new ImageData(dst, dstW, dstH);
+    }
+}
+exports.DeepZoomGenerator = DeepZoomGenerator;
+//# sourceMappingURL=deep-zoom.js.map

package/dist/cjs/deep-zoom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-zoom.js","sourceRoot":"","sources":["../../src/deep-zoom.ts"],"names":[],"mappings":"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"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,9 @@
+/** Base error class for all OpenSlide errors. */
+export declare class OpenSlideError extends Error {
+    constructor(message: unknown);
+}
+/** Thrown when the file format is not supported by OpenSlide. */
+export declare class OpenSlideUnsupportedFormatError extends OpenSlideError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,OAAO;CAS7B;AAED,iEAAiE;AACjE,qBAAa,+BAAgC,SAAQ,cAAc;gBACrD,OAAO,CAAC,EAAE,MAAM;CAK7B"}