napari-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baha Elkassaby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# napari-js
+
+A browser-native, **WebGPU** rendering engine that ports the visualization model of
+[napari](https://napari.org) (the Python multi-dimensional image viewer) to TypeScript.
+
+> **Status:** **NJ-5+ complete — Phase B roadmap done.** Added volume rendering:
+> `viewer.addVolume()` fragment-raymarches a 3D texture (MIP / translucent DVR / iso-surface
+> with gradient shading) via a fullscreen quad + ray-box intersection in volume space; a
+> `Camera3D` orbit camera and `dims.ndisplay = 3` mode drive it (visuals are routed by
+> dimensionality). Full 3D matrix math (`perspective`/`lookAt`/`invert`) is unit-tested.
+> napari-js now spans NJ-0…NJ-5+: images (single/multi-channel/16-bit), tiled+z-stacks,
+> points, labels, volume, plus readback/screenshot/histogram. All gates green (typecheck /
+> lint / 83 unit tests / build). **Remaining:** `npm publish` (registry auth) and — when you
+> choose — Phase C, the `jit-ui` `IVisualizer` adapter ([docs/06](./docs/06-jit-ui-integration.md)).
+
+## Quickstart
+
+```bash
+npm install
+npm run dev        # open the printed URL in a WebGPU browser → see the demo quad
+npm test           # GPU-free unit tests (Vitest)
+npm run typecheck  # tsc --noEmit
+npm run lint       # eslint
+npm run build      # library bundle + types → dist/
+```
+
+`npm run dev` serves `index.html` → `playground/main.ts`, which creates a `Viewer`, awaits
+its WebGPU device, and renders the NJ-0 demo. If WebGPU is unavailable the page shows the
+reason instead of crashing.
+
+## What this is
+
+napari-js is a **standalone, framework-agnostic** library. It renders large
+multi-dimensional / multi-channel scientific images in the browser on the GPU, with
+napari's model: a `Viewer` holding a list of `Layer`s (Image, later Points / Labels /
+Volume), each with its own colormap (LUT), contrast limits, gamma, opacity, and blending.
+
+It is **not** a port of napari's Python code or its Qt GUI. It is a faithful port of
+napari's _rendering concepts_ — the layer→visual model, per-layer GPU colormapping,
+serializable transforms and camera — onto WebGPU and WGSL. See
+[`docs/07-napari-concept-mapping.md`](./docs/07-napari-concept-mapping.md).
+
+## Why
+
+WebGPU now ships in all major browsers (late 2025). napari's strengths — GPU
+multi-channel fluorescence compositing, live scalar colormapping, and volume rendering —
+are exactly the things current browser image viewers do poorly or on the CPU. napari-js
+brings those strengths to the web as a reusable npm package.
+
+## Where it fits
+
+```
+~/git/napari      Reference: the Python renderer being ported (napari/_vispy, layers, components)
+~/git/napari-js   THIS repo: the standalone TS + WebGPU port, published to npm
+~/git/jit-ui      Eventual consumer: jax-image-visualization adds a napari-js IVisualizer backend
+```
+
+The first downstream consumer will be the `jax-image-visualization` library in the
+`jit-ui` monorepo, which will add napari-js as a new `IVisualizer` backend alongside its
+OpenSeadragon and Plotly backends. **That integration is a later phase** (see
+[`docs/06-jit-ui-integration.md`](./docs/06-jit-ui-integration.md)); napari-js is built
+and published independently first.
+
+## Docs
+
+| Doc                                                                | Contents                                                                            |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| [00 — Feasibility](./docs/00-feasibility.md)                       | Why this is feasible: napari architecture findings, what ports cleanly, what's hard |
+| [01 — Architecture](./docs/01-architecture.md)                     | Engine module layout, render loop, design principles                                |
+| [02 — Public API](./docs/02-public-api.md)                         | The `Viewer` / `Layer` / `Colormap` / `TextureSource` API surface                   |
+| [03 — RenderState IR](./docs/03-render-state-ir.md)                | The serializable intermediate representation between model and GPU                  |
+| [04 — WGSL rendering plan](./docs/04-wgsl-rendering-plan.md)       | Shader pipelines: image+colormap, multi-channel compositing, future raycasting      |
+| [05 — Roadmap](./docs/05-roadmap.md)                               | Milestones NJ-0 … NJ-5+                                                             |
+| [06 — jit-ui integration](./docs/06-jit-ui-integration.md)         | Phase C: the `IVisualizer` adapter in jax-image-visualization (deferred)            |
+| [07 — napari concept mapping](./docs/07-napari-concept-mapping.md) | How each napari concept maps to napari-js                                           |
+
+## Acknowledgments
+
+Built with the help of Claude Opus 4.8 (Anthropic).
+
+## License
+
+[MIT](./LICENSE) © Baha Elkassaby

package/dist/cache/lru.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bounded least-recently-used cache. Insertion/`get` mark an entry most-recently-used; when
+ * size exceeds `capacity` the oldest entries are evicted via `onEvict` (used to destroy GPU
+ * textures). Relies on `Map` preserving insertion order.
+ */
+export declare class LruCache<V> {
+    private readonly capacity;
+    private readonly onEvict?;
+    private readonly map;
+    constructor(capacity: number, onEvict?: ((value: V, key: string) => void) | undefined);
+    get size(): number;
+    has(key: string): boolean;
+    /** Get a value and mark it most-recently-used. */
+    get(key: string): V | undefined;
+    /** Insert/update a value (most-recently-used), evicting the oldest beyond capacity. */
+    set(key: string, value: V): void;
+    delete(key: string): boolean;
+    clear(): void;
+}

package/dist/camera/camera.d.ts

@@ -0,0 +1,25 @@
+import { Emitter } from '../scene/events';
+import { Mat4 } from '../math/mat4';
+/**
+ * 2D orthographic pan/zoom camera. `center` is in world coordinates; `zoom` is canvas pixels
+ * per world unit. Emits {@link changed} on any mutation so the viewer can schedule a redraw.
+ * The 3D arcball camera arrives in NJ-5+.
+ */
+export declare class Camera {
+    readonly changed: Emitter<Camera>;
+    private _center;
+    private _zoom;
+    get center(): [number, number];
+    set center(value: readonly [number, number]);
+    get zoom(): number;
+    set zoom(value: number);
+    /** Set center + zoom in one mutation (single change event). */
+    set(center: readonly [number, number], zoom: number): void;
+    /** World→clip view-projection matrix for a `vw`×`vh` viewport. */
+    viewProjection(vw: number, vh: number): Mat4;
+    /**
+     * Frame a `width`×`height` region centered in a `vw`×`vh` viewport (with a little margin),
+     * e.g. to fit a freshly loaded image. No-op for degenerate inputs.
+     */
+    fit(width: number, height: number, vw: number, vh: number, margin?: number): void;
+}

package/dist/camera/camera3d.d.ts

@@ -0,0 +1,28 @@
+import { Emitter } from '../scene/events';
+import { Mat4, Vec3 } from '../math/mat4';
+/**
+ * Orbit camera for 3D (volume) rendering: spins around `target` at `distance`, parameterized
+ * by `azimuth`/`elevation`. Produces a perspective view-projection. Emits {@link changed} on
+ * mutation. Used when `dims.ndisplay === 3`.
+ */
+export declare class Camera3D {
+    readonly changed: Emitter<Camera3D>;
+    azimuth: number;
+    elevation: number;
+    fov: number;
+    private _distance;
+    private _target;
+    get distance(): number;
+    set distance(value: number);
+    get target(): [number, number, number];
+    set target(value: Vec3);
+    /** Rotate the orbit by deltas (radians); elevation is clamped to avoid gimbal flip. */
+    orbit(dAzimuth: number, dElevation: number): void;
+    zoomBy(factor: number): void;
+    /** Eye position in world space. */
+    eye(): [number, number, number];
+    /** Perspective view-projection for a `vw`×`vh` viewport. */
+    viewProjection(vw: number, vh: number): Mat4;
+    /** Frame a `[w,h,d]` volume centered at the origin. */
+    frame(w: number, h: number, d: number): void;
+}

package/dist/camera/controls.d.ts

@@ -0,0 +1,7 @@
+import { Camera } from './camera';
+/**
+ * Attach pointer-drag panning and wheel zoom (zoom about the cursor) to a canvas. Returns a
+ * detach function. World/screen conversion uses the camera's current center+zoom and the
+ * canvas's CSS size (Y flipped to match {@link ortho2d}).
+ */
+export declare function attachCameraControls(canvas: HTMLCanvasElement, camera: Camera): () => void;

package/dist/camera/controls3d.d.ts

@@ -0,0 +1,6 @@
+import { Camera3D } from './camera3d';
+/**
+ * Attach orbit controls to a canvas: drag rotates (azimuth/elevation), wheel dollies in/out.
+ * Returns a detach function.
+ */
+export declare function attachOrbitControls(canvas: HTMLCanvasElement, camera: Camera3D): () => void;

package/dist/color/checkerboard.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generate an `size`×`size` RGBA8 checkerboard with `cells` squares per side. Used by the
+ * NJ-0 demo to prove texture upload + sampling. Pure and GPU-free (unit-tested).
+ */
+export declare function makeCheckerboard(size: number, cells?: number): Uint8Array<ArrayBuffer>;

package/dist/color/colormap.d.ts

@@ -0,0 +1,26 @@
+export type RGB = [number, number, number];
+/** A control point in a colormap: normalized position `t` (0..1) → linear RGB (0..1). */
+export interface ColorStop {
+    t: number;
+    color: RGB;
+}
+/**
+ * A colormap defined by sorted control points, linearly interpolated. Mirrors napari's
+ * `Colormap` concept; sampled into a LUT texture for the GPU (see ./lut.ts).
+ */
+export declare class Colormap {
+    readonly name: string;
+    readonly stops: ColorStop[];
+    constructor(name: string, stops: ColorStop[]);
+    /** Sample the colormap at `t` (clamped to 0..1), returning linear RGB. */
+    sample(t: number): RGB;
+}
+export declare const GRAY: Colormap;
+export declare const RED: Colormap;
+export declare const GREEN: Colormap;
+export declare const BLUE: Colormap;
+export declare const VIRIDIS: Colormap;
+export declare const MAGMA: Colormap;
+export declare const NAMED_COLORMAPS: Record<string, Colormap>;
+/** Resolve a colormap name or pass through a `Colormap`. Throws on an unknown name. */
+export declare function resolveColormap(cmap: Colormap | string): Colormap;

package/dist/color/display-pipeline.d.ts

@@ -0,0 +1,22 @@
+import { Colormap, RGB } from './colormap';
+/**
+ * CPU reference for the scalar display math the `image-colormap` WGSL shader performs:
+ * window → invert → gamma. Returns the normalized LUT coordinate `t` in 0..1. Kept pure and
+ * tested so the shader has a ground truth (see docs/04) and so histograms/readback can reuse
+ * the exact same math. `value` and the clim are in the same units.
+ */
+export declare function windowGamma(value: number, climLo: number, climHi: number, gamma: number, invert: boolean): number;
+/** Map a scalar value through window/gamma and a colormap to linear RGB. */
+export declare function mapScalar(value: number, opts: {
+    climLo: number;
+    climHi: number;
+    gamma: number;
+    invert: boolean;
+    colormap: Colormap;
+}): RGB;
+/**
+ * Additive composite of premultiplied RGB contributions (channels with `blending: 'additive'`
+ * over a black background), clamped to 1 — the CPU reference for multi-channel fluorescence.
+ */
+export declare function additiveComposite(colors: readonly RGB[]): RGB;
+export declare function clamp01(x: number): number;

package/dist/color/histogram.d.ts

@@ -0,0 +1,14 @@
+/** A binned intensity histogram over a value range. */
+export interface Histogram {
+    counts: Uint32Array;
+    bins: number;
+    min: number;
+    max: number;
+}
+/** Rec.601 luma of an 8-bit RGB triple (0..255). */
+export declare function luminance8(r: number, g: number, b: number): number;
+/**
+ * Histogram of per-pixel luminance over RGBA8 data (alpha ignored), `bins` bins across the
+ * 0..255 range. Pure and GPU-free (unit-tested); the viewer feeds it readback pixels.
+ */
+export declare function histogramRGBA(data: Uint8ClampedArray | Uint8Array, bins: number): Histogram;

package/dist/color/label-colormap.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Build a cyclic label color LUT: an `size`×1 RGBA8 table indexed by `labelId % size`. Entry
+ * 0 is fully transparent (background); the rest are distinct hues spaced by the golden ratio
+ * so adjacent ids contrast. Pure and GPU-free (unit-tested). Mirrors napari's cyclic label
+ * colormap.
+ */
+export declare function buildLabelLut(size?: number): Uint8Array<ArrayBuffer>;

package/dist/color/lut.d.ts

@@ -0,0 +1,9 @@
+import { Colormap } from './colormap';
+/** Default LUT resolution: 256 entries, the napari/OpenGL convention. */
+export declare const LUT_SIZE = 256;
+/**
+ * Build an `size`×1 RGBA8 lookup table from a colormap by sampling at evenly spaced
+ * positions. Suitable for upload as a `rgba8unorm` texture sampled by the fragment shader.
+ * Pure and GPU-free (unit-tested).
+ */
+export declare function buildLut(colormap: Colormap, size?: number): Uint8Array<ArrayBuffer>;

package/dist/engine/canvas.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Owns a canvas's WebGPU context: format negotiation, configuration, and DPR-aware sizing.
+ * The render loop reads {@link view} each frame for the current swapchain texture.
+ */
+export declare class CanvasTarget {
+    readonly canvas: HTMLCanvasElement;
+    readonly device: GPUDevice;
+    readonly context: GPUCanvasContext;
+    readonly format: GPUTextureFormat;
+    constructor(canvas: HTMLCanvasElement, device: GPUDevice, format?: GPUTextureFormat);
+    /** (Re)configure the swapchain for the current device/format. */
+    configure(): void;
+    /**
+     * Resize the backing buffer to match the canvas's CSS size × DPR, clamped to the device's
+     * max texture dimension. Returns `true` when the size actually changed.
+     */
+    syncSize(dpr?: number): boolean;
+    /** The current swapchain texture view for this frame. */
+    get view(): GPUTextureView;
+}

package/dist/engine/device.d.ts

@@ -0,0 +1,23 @@
+/** GPU features napari-js opts into when the adapter supports them. */
+export interface DeviceFeatures {
+    /** Linear filtering of `r32float` textures (else 16-bit/float layers fall back to nearest). */
+    float32Filterable: boolean;
+}
+/** A live WebGPU adapter + device pair plus the negotiated optional features. */
+export interface DeviceContext {
+    adapter: GPUAdapter;
+    device: GPUDevice;
+    features: DeviceFeatures;
+}
+/** Thrown when WebGPU is unavailable or no adapter/device can be obtained. */
+export declare class WebGPUUnsupportedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Acquire a WebGPU device, opting into `float32-filterable` when available. Throws
+ * {@link WebGPUUnsupportedError} with an actionable message when the environment lacks
+ * `navigator.gpu`, has no suitable adapter, or device creation fails.
+ */
+export declare function acquireDevice(options?: {
+    powerPreference?: GPUPowerPreference;
+}): Promise<DeviceContext>;

package/dist/engine/readback.d.ts

@@ -0,0 +1,13 @@
+/** Composited pixels read back from the GPU (RGBA8, top row first). */
+export interface PixelData {
+    width: number;
+    height: number;
+    channels: number;
+    data: Uint8ClampedArray;
+}
+/**
+ * Copy an `rgba8unorm` texture to the CPU as tightly-packed RGBA bytes. Handles WebGPU's
+ * 256-byte `bytesPerRow` alignment by unpadding each row. The texture must have been created
+ * with `COPY_SRC` usage.
+ */
+export declare function readTextureToRGBA(device: GPUDevice, texture: GPUTexture, width: number, height: number): Promise<Uint8ClampedArray>;

package/dist/engine/renderer.d.ts

@@ -0,0 +1,42 @@
+import { CanvasTarget } from './canvas';
+import { Camera } from '../camera/camera';
+import { Camera3D } from '../camera/camera3d';
+import { Layer } from '../layers/layer';
+/** Camera/dims inputs the viewer hands to a render call (viewport size is filled internally). */
+export interface RenderInputs {
+    camera2d: Camera;
+    camera3d: Camera3D;
+    ndisplay: 2 | 3;
+    z: number;
+}
+export interface RendererOptions {
+    float32Filterable: boolean;
+    /** Called when an async tile upload completes, so the host can schedule a redraw. */
+    onNeedsRedraw: () => void;
+}
+/**
+ * Scene renderer: owns one {@link LayerVisual} per layer (a single-image or tiled visual,
+ * chosen by source kind) and draws them in order each frame. Layer lifecycle is driven by
+ * the {@link Viewer}; this class only uploads, syncs, and draws.
+ */
+export declare class Renderer {
+    private readonly device;
+    private readonly target;
+    private readonly options;
+    private readonly visuals;
+    constructor(device: GPUDevice, target: CanvasTarget, options?: RendererOptions);
+    addLayer(layer: Layer): void;
+    private createVisual;
+    removeLayer(id: string): void;
+    has(id: string): boolean;
+    /** Draw the given layers (in order) into the swapchain for the current cameras/dims. */
+    render(inputs: RenderInputs, layers: readonly Layer[], background?: GPUColor): void;
+    /**
+     * Draw into an arbitrary color-attachment view. `vw`/`vh` are the CSS-pixel projection size
+     * (resolution-independent); the attachment may be a different device-pixel size. Only
+     * visuals whose `ndisplay` matches `inputs.ndisplay` are drawn. Used for both the swapchain
+     * and offscreen readback.
+     */
+    renderInto(view: GPUTextureView, inputs: RenderInputs, layers: readonly Layer[], vw: number, vh: number, background?: GPUColor): void;
+    dispose(): void;
+}

package/dist/engine/viewport.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the backing drawing-buffer size from a canvas's CSS size and the device pixel
+ * ratio, clamped to the GPU's maximum 2D texture dimension. Pure and GPU-free so it can be
+ * unit-tested directly.
+ *
+ * - Non-positive `devicePixelRatio` falls back to 1.
+ * - Each dimension is clamped to `[1, maxDimension]` and rounded to an integer.
+ */
+export declare function resolveDrawingBufferSize(cssWidth: number, cssHeight: number, devicePixelRatio: number, maxDimension: number): {
+    width: number;
+    height: number;
+};

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export { Viewer } from './viewer';
+export type { ViewerOptions } from './viewer';
+export { acquireDevice, WebGPUUnsupportedError } from './engine/device';
+export type { DeviceContext, DeviceFeatures } from './engine/device';
+export type { PixelData } from './engine/readback';
+export { histogramRGBA, luminance8 } from './color/histogram';
+export type { Histogram } from './color/histogram';
+export { ViewerModel } from './scene/viewer-model';
+export { LayerList } from './scene/layer-list';
+export { Dims } from './scene/dims';
+export { Camera } from './camera/camera';
+export { Camera3D } from './camera/camera3d';
+export { Layer } from './layers/layer';
+export type { BlendMode } from './layers/layer';
+export { ImageLayer } from './layers/image-layer';
+export type { ImageLayerOptions, Interpolation } from './layers/image-layer';
+export { PointsLayer } from './layers/points-layer';
+export type { PointsLayerOptions, PointSymbol, RGBA } from './layers/points-layer';
+export { LabelsLayer } from './layers/labels-layer';
+export type { LabelsLayerOptions } from './layers/labels-layer';
+export { VolumeLayer } from './layers/volume-layer';
+export type { VolumeLayerOptions, VolumeRendering } from './layers/volume-layer';
+export { nearestPointIndex } from './picking/pick';
+export { Colormap, resolveColormap, NAMED_COLORMAPS, GRAY, RED, GREEN, BLUE, VIRIDIS, MAGMA, } from './color/colormap';
+export type { RGB, ColorStop } from './color/colormap';
+export { buildLut, LUT_SIZE } from './color/lut';
+export { buildLabelLut } from './color/label-colormap';
+export { windowGamma, mapScalar, additiveComposite } from './color/display-pipeline';
+export { toTextureSource, defaultContrastLimits, isGrayscale, channelsOf, depthOf, } from './io/texture-source';
+export type { TextureSource, TypedImageSource, ExternalImageSource, TiledSource, TileKey, PixelChunk, ImageInput, PixelDtype, } from './io/texture-source';
+export { selectLevel, levelScale, levelDims, tileGrid, visibleTiles, worldViewport, } from './io/pyramid';
+export type { Rect, VisibleTile } from './io/pyramid';
+export { LruCache } from './cache/lru';
+export { VERSION } from './version';

package/dist/io/pyramid.d.ts

@@ -0,0 +1,41 @@
+/** An axis-aligned rectangle in level-0 (full-resolution) data coordinates. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A visible tile plus its rect in level-0 data coordinates (so the camera is uniform). */
+export interface VisibleTile {
+    col: number;
+    row: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Downsample factor of a pyramid level (level 0 = 1, level 1 = 2, …). */
+export declare function levelScale(level: number): number;
+/** Pixel dimensions of a pyramid level. */
+export declare function levelDims(width: number, height: number, level: number): {
+    width: number;
+    height: number;
+};
+/** Tile grid (cols × rows) at a level. */
+export declare function tileGrid(width: number, height: number, level: number, tileSize: number): {
+    cols: number;
+    rows: number;
+};
+/**
+ * Choose the pyramid level whose texels are ≈1 screen pixel for `zoom` (CSS px per level-0
+ * unit). Zoomed in (zoom ≥ 1) → level 0; each halving of zoom steps one level coarser.
+ * Clamped to `[0, levels-1]`.
+ */
+export declare function selectLevel(zoom: number, levels: number): number;
+/** The level-0 data rectangle currently visible for a camera and CSS viewport size. */
+export declare function worldViewport(centerX: number, centerY: number, zoom: number, vw: number, vh: number): Rect;
+/**
+ * Tiles of `level` that overlap `view` (level-0 coords), with each tile's rect in level-0
+ * coords (edge tiles clipped to the image bounds). Empty when the view misses the image.
+ */
+export declare function visibleTiles(view: Rect, width: number, height: number, level: number, tileSize: number): VisibleTile[];

package/dist/io/texture-source.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pixel ingestion for NJ-1: a single full-resolution image (no tiling — that arrives in
+ * NJ-3 as a pyramidal `TiledSource`). A source is either raw typed-array pixels or an
+ * external decoded image (ImageBitmap/canvas) uploaded via `copyExternalImageToTexture`.
+ */
+export type PixelDtype = 'uint8' | 'uint16' | 'float32';
+/**
+ * Raw scalar/RGBA pixels in a typed array. `uint8` → `r8unorm`/`rgba8unorm`;
+ * `uint16`/`float32` scalar → `r32float` (native-precision windowing). RGBA is `uint8` only.
+ */
+export interface TypedImageSource {
+    readonly kind: 'typed';
+    readonly width: number;
+    readonly height: number;
+    readonly channels: 1 | 4;
+    readonly dtype: PixelDtype;
+    readonly data: Uint8Array | Uint16Array | Float32Array;
+}
+/** A decoded image to upload directly to an RGBA8 texture. */
+export interface ExternalImageSource {
+    readonly kind: 'external';
+    readonly width: number;
+    readonly height: number;
+    readonly image: ImageBitmap | HTMLCanvasElement | OffscreenCanvas | HTMLImageElement;
+}
+/** Identifies one tile within a pyramidal/tiled source. */
+export interface TileKey {
+    /** Pyramid level (0 = full resolution; each level halves resolution). */
+    level: number;
+    col: number;
+    row: number;
+    /** Z-slice (0 when not a stack). */
+    z: number;
+}
+/** Pixels for one tile. Edge tiles may be smaller than the nominal `tileSize`. */
+export interface PixelChunk {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint16Array | Float32Array;
+}
+/**
+ * A pyramidal, tiled, optionally z-stacked image — the general large-image case (whole-slide
+ * microscopy etc.). `width`/`height` are full-resolution (level 0). Tiles are fetched lazily
+ * via {@link fetchTile} and cached on the GPU. The host supplies `fetchTile` (e.g. a server
+ * `/tile` request); napari-js stays ignorant of any backend.
+ */
+export interface TiledSource {
+    readonly kind: 'tiled';
+    readonly width: number;
+    readonly height: number;
+    readonly tileSize: number;
+    readonly levels: number;
+    readonly depth: number;
+    readonly channels: 1 | 4;
+    readonly dtype: PixelDtype;
+    fetchTile(key: TileKey): Promise<PixelChunk>;
+}
+export type TextureSource = TypedImageSource | ExternalImageSource | TiledSource;
+/** Anything `Viewer.addImage` accepts. */
+export type ImageInput = TypedImageSource | TiledSource | ImageBitmap | HTMLCanvasElement | HTMLImageElement;
+export declare function channelsOf(source: TextureSource): 1 | 4;
+/** Number of z-slices in a source (1 unless it's a z-stacked tiled source). */
+export declare function depthOf(source: TextureSource): number;
+export declare function isGrayscale(source: TextureSource): boolean;
+/** Default contrast-limit window for a source, in source-data units. */
+export declare function defaultContrastLimits(source: TextureSource): [number, number];
+/** Normalize a user input into a {@link TextureSource}. */
+export declare function toTextureSource(input: ImageInput): TextureSource;

package/dist/layers/image-layer.d.ts

@@ -0,0 +1,47 @@
+import { Layer, BlendMode } from './layer';
+import { Colormap } from '../color/colormap';
+import { TextureSource } from '../io/texture-source';
+export type Interpolation = 'nearest' | 'linear';
+export interface ImageLayerOptions {
+    name?: string;
+    /** Scalar colormap; ignored for RGB(A) sources (rendered directly). Defaults to gray. */
+    colormap?: Colormap | string;
+    /** Normalization window in source-data units. Defaults to the source's dtype range. */
+    contrastLimits?: [number, number];
+    gamma?: number;
+    invert?: boolean;
+    opacity?: number;
+    blending?: BlendMode;
+    visible?: boolean;
+    interpolation?: Interpolation;
+    scale?: [number, number];
+    translate?: [number, number];
+}
+/**
+ * A 2D image layer. Carries the source pixels plus the scalar display pipeline
+ * (contrast/gamma/invert/colormap). Display setters are reactive; changing them updates GPU
+ * uniforms/LUT — never re-uploads the texture (tracked via {@link colormapVersion}).
+ */
+export declare class ImageLayer extends Layer {
+    readonly kind = "image";
+    readonly source: TextureSource;
+    readonly grayscale: boolean;
+    /** Bumped whenever the colormap changes so the visual knows to rebuild its LUT. */
+    colormapVersion: number;
+    private _colormap;
+    private _contrastLimits;
+    private _gamma;
+    private _invert;
+    private _interpolation;
+    constructor(source: TextureSource, opts?: ImageLayerOptions);
+    get colormap(): Colormap | null;
+    set colormap(value: Colormap | string | null);
+    get contrastLimits(): [number, number];
+    set contrastLimits(value: readonly [number, number]);
+    get gamma(): number;
+    set gamma(value: number);
+    get invert(): boolean;
+    set invert(value: boolean);
+    get interpolation(): Interpolation;
+    set interpolation(value: Interpolation);
+}

package/dist/layers/labels-layer.d.ts

@@ -0,0 +1,32 @@
+import { Layer, BlendMode } from './layer';
+export interface LabelsLayerOptions {
+    name?: string;
+    /** Highlight this label id when {@link showSelectedOnly} is set. */
+    selectedLabel?: number;
+    showSelectedOnly?: boolean;
+    opacity?: number;
+    blending?: BlendMode;
+    visible?: boolean;
+    scale?: [number, number];
+    translate?: [number, number];
+}
+/**
+ * A segmentation/label layer (the napari Labels analog). `data` is an 8-bit integer label
+ * image (ids 0..255; 0 = background/transparent), colored by a cyclic LUT. Sampled with
+ * nearest filtering so label edges stay crisp. uint16/uint32 label support is a follow-up.
+ */
+export declare class LabelsLayer extends Layer {
+    readonly kind = "labels";
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array;
+    private _selectedLabel;
+    private _showSelectedOnly;
+    constructor(data: Uint8Array, width: number, height: number, opts?: LabelsLayerOptions);
+    get selectedLabel(): number;
+    set selectedLabel(value: number);
+    get showSelectedOnly(): boolean;
+    set showSelectedOnly(value: boolean);
+    /** Label id at data pixel `(x, y)`, or 0 (background) if out of bounds. */
+    labelAt(x: number, y: number): number;
+}