@lancercomet/zoom-pan 0.3.0 → 0.4.0

package/README.md

@@ -1,18 +1,35 @@
 # ZoomPan
 
-A lightweight **canvas viewport control library** for 2D applications.  
-Provides smooth **panning**, **zooming**, **pinch-to-zoom**, and **inertia** behaviors.
+
+ZoomPan is a **2D rendering viewport / render-pipeline library**.
+
+It is **not** a scene-graph engine. If you are looking for a full display tree, rich shape primitives, filters, batching, and a large ecosystem, you probably want **PixiJS** / **Fabric.js** / **Konva**.
+
+It provides a consistent world/screen coordinate model, pan/zoom interactions, a pluggable render pipeline (RenderPipeline/Pass), a layer system, and optional rendering backends (Canvas2D/WebGL).
+
+Use it as a simple “image viewer with pan & zoom”, or as the rendering core of a “drawing app / annotation tool / editor”.
+
+## ZoomPan vs Pixi / Fabric / Konva
+
+| Topic | ZoomPan | Pixi / Fabric / Konva |
+| --- | --- | --- |
+| Primary goal | Viewport + render orchestration for editor-style apps | General-purpose 2D rendering engine / scene graph |
+| Best for | Zoom/pan canvas viewers, drawing apps, editors, annotation tools | Complex object trees, shape primitives, filters, rich rendering features |
+| Extension model | Explicit render pipeline passes + plugins | Scene graph + framework lifecycle + ecosystem plugins |
+| World/screen split | Built-in phases: `world` and `screen` | Often requires custom conventions / layers / containers |
+| What it does **not** try to be | A full engine with display tree, batching, filters | A small viewport kernel |
 
 ## Features
 
-- Mouse pan & wheel zoom
-- Touch pan & pinch-to-zoom (always works, even in drawing mode)
-- Pen/stylus support for drawing apps
-- Layer-based rendering system
-- Built-in undo/redo support
-- Document bounds with margins
+- **Selectable renderer backend**: `renderer: 'canvas2d' | 'webgl' | 'auto' | IRenderer`
+- **Pluggable render pipeline**: 4 phases `beforeWorld / world / afterWorld / screen` + stable ordering via `order`
+- **Viewport transform**: pan/zoom + world ↔ screen coordinate conversion
+- **Interaction plugin**: mouse/touch/pen input + inertia + `cancel()` for focus-loss cleanup
+- **Layer system**: split world/screen rendering (you can insert passes between them)
+- **Bounds (document bounds)**: background/shadow/clip/border, pan clamping, `zoomToFit({ maxScale })`
+- **History (Undo/Redo)**: provided via plugin/examples (see `examples/`)
 
-## Installation
+## Install
 
 ```bash
 npm install @lancercomet/zoom-pan
@@ -22,27 +39,28 @@ npm install @lancercomet/zoom-pan
 
 ### Image Viewer
 
-```typescript
+```ts
 import { ViewManager, ContentLayerManager, createInteractionPlugin } from '@lancercomet/zoom-pan'
 
-const layerManager = new ContentLayerManager()
+const content = new ContentLayerManager()
 
-const view = new ViewManager(canvas)
+const view = new ViewManager(canvas, {
+  renderer: 'auto' // 'canvas2d' | 'webgl' | 'auto'
+})
 
-view.registerLayerManager(layerManager)
+view.registerLayerManager(content)
 view.use(createInteractionPlugin())
 
-// Add an image
-await layerManager.createImageLayer({
+await content.createImageLayer({
   src: 'image.png',
   x: 0,
   y: 0
 })
 ```
 
-### Drawing App
+### Drawing App (simplified)
 
-```typescript
+```ts
 import {
   ViewManager,
   ContentLayerManager,
@@ -53,41 +71,39 @@ import {
   createSnapshotCommand
 } from '@lancercomet/zoom-pan'
 
-const layerManager = new ContentLayerManager()
-const historyManager = new HistoryManager({ maxHistorySize: 50 })
-
-const view = new ViewManager(canvas)
+const content = new ContentLayerManager()
+const history = new HistoryManager({ maxHistorySize: 50 })
 
-view.registerLayerManager(layerManager)
+const view = new ViewManager(canvas, { renderer: 'auto' })
+view.registerLayerManager(content)
 
-// Interaction plugin: controls pan/zoom
+// Interaction plugin controls pan/zoom.
 // - Touch gestures (pan/pinch) always work
-// - Mouse/pen pan controlled by setPanEnabled()
+// - Mouse/pen pan is controlled by setPanEnabled()
 const interaction = view.use(createInteractionPlugin())
 
-// Document plugin: sets canvas bounds
-const doc = view.use(createBoundsPlugin({
+// Bounds defines document rect/margins and clamps pan.
+const bounds = view.use(createBoundsPlugin({
   rect: { x: 0, y: 0, width: 1200, height: 800 },
   margins: { left: 50, right: 50, top: 50, bottom: 50 }
 }))
-doc.zoomToFit()
 
-// Create drawable layer
-const drawLayer = new CanvasLayer({
-  width: 1200,
-  height: 800
-})
-layerManager.addLayer(drawLayer)
+// Prevent upscaling small documents
+bounds.zoomToFit({ maxScale: 1 })
 
-// Switch to drawing mode (disable mouse/pen pan, touch still works)
+const drawLayer = new CanvasLayer({ width: 1200, height: 800 })
+content.addLayer(drawLayer)
+
+// Drawing mode: disable mouse/pen pan (touch still works)
 interaction.setPanEnabled(false)
 
-// Drawing with undo support
+// On focus loss, cancel any ongoing drag/pinch/inertia
+window.addEventListener('blur', () => interaction.cancel())
+
 let snapshotBefore: ImageData | null = null
 
 canvas.onpointerdown = (e) => {
-  if (e.pointerType === 'touch') return // Let plugin handle touch
-  
+  if (e.pointerType === 'touch') return
   const { wx, wy } = view.toWorld(e.offsetX, e.offsetY)
   snapshotBefore = drawLayer.captureSnapshot()
   drawLayer.beginStroke(wx, wy)
@@ -96,7 +112,6 @@ canvas.onpointerdown = (e) => {
 canvas.onpointermove = (e) => {
   if (e.pointerType === 'touch') return
   if (e.buttons !== 1) return
-  
   const { wx, wy } = view.toWorld(e.offsetX, e.offsetY)
   drawLayer.stroke(wx, wy, '#000', 10, e.pressure, 'brush')
   view.requestRender()
@@ -106,13 +121,7 @@ canvas.onpointerup = () => {
   drawLayer.endStroke()
   const snapshotAfter = drawLayer.captureSnapshot()
   const cmd = createSnapshotCommand(drawLayer, snapshotBefore, snapshotAfter)
-  if (cmd) historyManager.addCommand(cmd)
-}
-
-// Undo/Redo
-document.onkeydown = (e) => {
-  if (e.ctrlKey && e.key === 'z') historyManager.undo()
-  if (e.ctrlKey && e.key === 'y') historyManager.redo()
+  if (cmd) history.addCommand(cmd)
 }
 ```
 
@@ -120,102 +129,134 @@ document.onkeydown = (e) => {
 
 ### ViewManager
 
-The main viewport controller. Handles coordinate transformation and rendering.
+The main controller: render loop, coordinate transforms, renderer backend, render pipeline, and plugins.
 
-```typescript
+```ts
 const view = new ViewManager(canvas, {
   minZoom: 0.2,
   maxZoom: 10,
-  background: '#fff'
+  background: '#fff',
+  renderer: 'auto'
 })
 
-// Coordinate conversion
 const { wx, wy } = view.toWorld(screenX, screenY)
-const { sx, sy } = view.toScreen(worldX, worldY)
+const { x, y } = view.toScreen(worldX, worldY)
 
-// Programmatic zoom
 view.zoomToAtScreen(anchorX, anchorY, 2.0)
 view.zoomByFactorAtScreen(anchorX, anchorY, 1.5)
 ```
 
+### Renderer Selection
+
+```ts
+import { ViewManager } from '@lancercomet/zoom-pan'
+
+new ViewManager(canvas, { renderer: 'canvas2d' })
+new ViewManager(canvas, { renderer: 'webgl' })
+new ViewManager(canvas, { renderer: 'auto' }) // tries WebGL first, falls back to Canvas2D
+```
+
+### RenderPipeline / Pass
+
+You can insert your own passes (e.g. draw a debug grid before world rendering):
+
+```ts
+view.addRenderPass({
+  name: 'debug.grid',
+  phase: 'beforeWorld',
+  order: -50,
+  render: ({ renderer }) => {
+    const ctx = renderer.getContentContext()
+    ctx.save()
+    ctx.strokeStyle = 'rgba(0,0,0,0.08)'
+    ctx.lineWidth = 1
+    // draw grid / guides here
+    ctx.restore()
+  }
+})
+```
+
 ### InteractionPlugin
 
-Handles user input for pan and zoom.
+```ts
+import { createInteractionPlugin } from '@lancercomet/zoom-pan'
 
-```typescript
 const interaction = view.use(createInteractionPlugin())
 
-// Pan enabled affects mouse/pen only
-// Touch gestures (single-finger pan, two-finger pinch) always work
-interaction.setPanEnabled(true)  // Mouse/pen can pan
-interaction.setPanEnabled(false) // Mouse/pen cannot pan (for drawing mode)
+interaction.setPanEnabled(true)  // mouse/pen can pan
+interaction.setPanEnabled(false) // mouse/pen cannot pan (drawing mode)
 
-interaction.setZoomEnabled(true) // Wheel zoom & pinch zoom enabled
+interaction.setZoomEnabled(true) // wheel zoom + pinch zoom
+
+interaction.cancel() // cancel drag/pinch/inertia (blur/visibilitychange)
 ```
 
 ### BoundsPlugin
 
-Defines document bounds and provides pan clamping.
+BoundsPlugin draws background/shadow, clips the world, and draws border via pipeline passes.
+It also supports per-instance pass ordering (useful when you need to insert your own passes around the bounds clip).
+
+```ts
+import { createBoundsPlugin } from '@lancercomet/zoom-pan'
 
-```typescript
-const doc = view.use(createBoundsPlugin({
+const bounds = view.use(createBoundsPlugin({
   rect: { x: 0, y: 0, width: 1200, height: 800 },
   margins: { left: 50, right: 50, top: 50, bottom: 50 },
   drawBorder: true,
   background: '#f0f0f0',
-  shadow: { blur: 20, color: 'rgba(0,0,0,0.3)', offsetX: 0, offsetY: 5 }
+  shadow: { blur: 20, color: 'rgba(0,0,0,0.3)', offsetX: 0, offsetY: 5 },
+  passOrder: {
+    beforeWorld: -100,
+    afterWorld: 100
+  }
 }))
 
-doc.zoomToFit()  // Fit document to viewport
-doc.setPanClampMode('minVisible')  // 'margin' | 'minVisible'
+bounds.zoomToFit({ maxScale: 1 })
+bounds.setPanClampMode('minVisible') // 'margin' | 'minVisible'
 ```
 
-### Layer System
+### Layers
 
-```typescript
-// Content layers (world space)
-const contentManager = new ContentLayerManager()
-view.registerLayerManager(contentManager)
+```ts
+import { ViewManager, ContentLayerManager, TopScreenLayerManager, CanvasLayer } from '@lancercomet/zoom-pan'
 
-// Canvas layer for drawing
-const layer = new CanvasLayer({ width: 1200, height: 800 })
-contentManager.addLayer(layer)
+const view = new ViewManager(canvas, { renderer: 'auto' })
 
-// Image layer
-const imgLayer = await contentManager.createImageLayer({ src: 'image.png' })
+// World-space content
+const content = new ContentLayerManager()
+view.registerLayerManager(content)
 
-// Remove layer (destroys it)
-contentManager.removeLayer(layer.id)
+// Screen-space overlay (UI / cursor / HUD)
+const overlay = new TopScreenLayerManager()
+view.registerLayerManager(overlay)
 
-// Detach layer (keeps it for undo)
-contentManager.detachLayer(layer.id)
+content.addLayer(new CanvasLayer({ width: 1200, height: 800 }))
 ```
 
-### History (Undo/Redo)
+Default rendering is split by pipeline phase:
 
-```typescript
-const history = new HistoryManager({ maxHistorySize: 50 })
+- `world`: calls each LayerManager's `renderWorldLayersIn(view)`
+- `screen`: calls each LayerManager's `renderScreenLayersIn(view)`
+
+This means you can insert passes between world and screen (e.g. selection overlay after world, UI in screen).
+
+## Plugin Lifecycle
 
-// Snapshot-based undo for drawing
-const before = layer.captureSnapshot()
-// ... draw ...
-const after = layer.captureSnapshot()
-const cmd = createSnapshotCommand(layer, before, after)
-if (cmd) history.addCommand(cmd)
+`ViewManager.use(plugin)` is transactional: if `install()` throws, it performs a best-effort rollback to avoid leaving a half-installed plugin behind.
 
-// Layer commands
-import { CreateLayerCommand, DeleteLayerCommand } from '@lancercomet/zoom-pan'
+```ts
+view.hasPlugin('bounds')
+view.listPlugins()
+view.clearPlugins()
 
-history.undo()
-history.redo()
-history.canUndo()
-history.canRedo()
+view.unuse('bounds')
 ```
 
 ## Examples
 
-See `examples/` folder:
+See `examples/`:
 
-- **`examples/viewer/`** - Simple image viewer
-- **`examples/painter/`** - Full drawing app with brush, eraser, layers, undo/redo
-- **`examples/doc/`** - Document mode demo with background and shadow
+- `examples/viewer/`: image viewer
+- `examples/painter/`: drawing app (brush/eraser/layers/undo-redo)
+- `examples/bounds/`: bounds (background/shadow/zoomToFit)
+- `examples/history/`: history (undo/redo)

package/dist/core/render-pipeline.d.ts

@@ -0,0 +1,24 @@
+import type { IRenderer } from './renderer/types';
+import type { ViewManager } from './view-manager';
+export type RenderPhase = 'beforeWorld' | 'world' | 'afterWorld' | 'screen';
+export interface RenderContext {
+    view: ViewManager;
+    renderer: IRenderer;
+}
+export interface RenderPass {
+    readonly name: string;
+    readonly phase: RenderPhase;
+    readonly order?: number;
+    enabled?: boolean;
+    render(ctx: RenderContext): void;
+}
+declare class RenderPipeline {
+    private readonly _passes;
+    addPass(pass: RenderPass): void;
+    removePass(name: string): void;
+    getPass(name: string): RenderPass | undefined;
+    listPasses(): RenderPass[];
+    renderPhase(phase: RenderPhase, ctx: RenderContext): void;
+    private _sort;
+}
+export { RenderPipeline };

package/dist/core/renderer/canvas2d-renderer.d.ts

@@ -0,0 +1,40 @@
+import type { IRenderer, IRendererTransform } from './types';
+/**
+ * Canvas 2D Renderer - the default renderer using Canvas 2D API.
+ */
+declare class Canvas2DRenderer implements IRenderer {
+    readonly type: "canvas2d";
+    private _canvas;
+    private _ctx;
+    private _contentCanvas;
+    private _contentCtx;
+    private _topScreenCanvas;
+    private _topScreenCtx;
+    private _dpr;
+    private _currentTransform;
+    init(canvas: HTMLCanvasElement): void;
+    dispose(): void;
+    resize(width: number, height: number, dpr: number): void;
+    clear(color: string | null): void;
+    beginFrame(): void;
+    endFrame(): void;
+    setWorldTransform(transform: IRendererTransform): void;
+    setScreenTransform(dpr: number): void;
+    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number, opacity?: number): void;
+    fillRect(x: number, y: number, w: number, h: number, color: string): void;
+    strokeRect(x: number, y: number, w: number, h: number, color: string, lineWidth?: number): void;
+    save(): void;
+    restore(): void;
+    clipRect(x: number, y: number, w: number, h: number): void;
+    getPixelColor(sx: number, sy: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    getContentContext(): CanvasRenderingContext2D;
+    getTopScreenContext(): CanvasRenderingContext2D;
+    get contentCanvas(): HTMLCanvasElement | null;
+    get topScreenCanvas(): HTMLCanvasElement | null;
+}
+export { Canvas2DRenderer };

package/dist/core/renderer/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './canvas2d-renderer';
+export * from './webgl-renderer';

package/dist/core/renderer/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Renderer interface - abstract away Canvas2D vs WebGL implementation.
+ */
+export interface IRendererTransform {
+    zoom: number;
+    tx: number;
+    ty: number;
+    dpr: number;
+}
+export interface IRendererSize {
+    width: number;
+    height: number;
+}
+/**
+ * Abstract renderer interface.
+ * Both Canvas2DRenderer and WebGLRenderer implement this.
+ */
+export interface IRenderer {
+    /**
+     * Renderer type identifier.
+     */
+    readonly type: 'canvas2d' | 'webgl';
+    /**
+     * Initialize the renderer with the target canvas.
+     */
+    init(canvas: HTMLCanvasElement): void;
+    /**
+     * Dispose all resources.
+     */
+    dispose(): void;
+    /**
+     * Resize internal buffers to match canvas size.
+     */
+    resize(width: number, height: number, dpr: number): void;
+    /**
+     * Clear the canvas with background color.
+     * @param color - CSS color string, null for transparent
+     */
+    clear(color: string | null): void;
+    /**
+     * Begin a new frame.
+     * Prepares internal state for rendering.
+     */
+    beginFrame(): void;
+    /**
+     * End frame and composite to screen.
+     */
+    endFrame(): void;
+    /**
+     * Set the current transform for world-space rendering.
+     */
+    setWorldTransform(transform: IRendererTransform): void;
+    /**
+     * Set transform for screen-space rendering (no zoom/pan, just DPR).
+     */
+    setScreenTransform(dpr: number): void;
+    /**
+     * Draw an image/canvas at the specified world position.
+     */
+    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number, opacity?: number): void;
+    /**
+     * Draw a rect (for backgrounds, borders, etc.)
+     */
+    fillRect(x: number, y: number, w: number, h: number, color: string): void;
+    /**
+     * Draw a stroked rect.
+     */
+    strokeRect(x: number, y: number, w: number, h: number, color: string, lineWidth?: number): void;
+    /**
+     * Save the current state (transform, clip, etc.)
+     */
+    save(): void;
+    /**
+     * Restore the previously saved state.
+     */
+    restore(): void;
+    /**
+     * Set a rectangular clip region.
+     */
+    clipRect(x: number, y: number, w: number, h: number): void;
+    /**
+     * Get pixel color at screen position.
+     * Returns RGBA values.
+     */
+    getPixelColor(sx: number, sy: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /**
+     * Get the content canvas/context for direct drawing (Canvas2D only).
+     * For WebGL, this returns a temporary 2D canvas that gets uploaded as texture.
+     */
+    getContentContext(): CanvasRenderingContext2D;
+    /**
+     * Get the top screen canvas/context for UI overlays.
+     */
+    getTopScreenContext(): CanvasRenderingContext2D;
+}
+/**
+ * Renderer type option for ViewManager.
+ */
+export type RendererType = 'canvas2d' | 'webgl' | 'auto' | IRenderer;

package/dist/core/renderer/webgl-renderer.d.ts

@@ -0,0 +1,64 @@
+import type { IRenderer, IRendererTransform } from './types';
+/**
+ * WebGL Renderer - GPU accelerated rendering using WebGL.
+ */
+declare class WebGLRenderer implements IRenderer {
+    readonly type: "webgl";
+    /**
+     * Check if WebGL is supported in the current browser.
+     */
+    static isSupported(): boolean;
+    private _canvas;
+    private _gl;
+    private _contentCanvas;
+    private _contentCtx;
+    private _topScreenCanvas;
+    private _topScreenCtx;
+    private _textureProgram;
+    private _colorProgram;
+    private _positionBuffer;
+    private _texCoordBuffer;
+    private _textureCache;
+    private _contentTexture;
+    private _topScreenTexture;
+    private _dpr;
+    private _width;
+    private _height;
+    private _currentTransform;
+    private _stateStack;
+    private _isContextLost;
+    private _onContextLost;
+    private _onContextRestored;
+    init(canvas: HTMLCanvasElement): void;
+    private _initWebGL;
+    private _createShader;
+    private _createProgram;
+    private _createTexture;
+    private _updateTexture;
+    dispose(): void;
+    resize(width: number, height: number, dpr: number): void;
+    clear(color: string | null): void;
+    private _parseColor;
+    beginFrame(): void;
+    endFrame(): void;
+    private _drawFullScreenQuad;
+    setWorldTransform(transform: IRendererTransform): void;
+    setScreenTransform(dpr: number): void;
+    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number, opacity?: number): void;
+    fillRect(x: number, y: number, w: number, h: number, color: string): void;
+    strokeRect(x: number, y: number, w: number, h: number, color: string, lineWidth?: number): void;
+    save(): void;
+    restore(): void;
+    clipRect(x: number, y: number, w: number, h: number): void;
+    getPixelColor(sx: number, sy: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    getContentContext(): CanvasRenderingContext2D;
+    getTopScreenContext(): CanvasRenderingContext2D;
+    get contentCanvas(): HTMLCanvasElement | null;
+    get topScreenCanvas(): HTMLCanvasElement | null;
+}
+export { WebGLRenderer };