docs: add dragOutside documentation and test

- Add comprehensive usage example with code snippets
- Create test file for dragOutside functionality
- Document browser support and benefits

Author: erik-balfe

DRAG_OUTSIDE_EXAMPLE.md

@@ -0,0 +1,57 @@
+# dragOutside Feature Example
+
+The `dragOutside` option allows dragging to continue even when the mouse/pointer leaves the canvas or browser window.
+
+## Basic Usage
+
+```javascript
+import { Viewport } from 'pixi-viewport';
+
+const viewport = new Viewport({
+    screenWidth: window.innerWidth,
+    screenHeight: window.innerHeight,
+    worldWidth: 2000,
+    worldHeight: 2000,
+    events: app.renderer.events
+});
+
+// Enable dragOutside
+viewport.drag({ 
+    dragOutside: true 
+});
+```
+
+## Options
+
+```javascript
+viewport.drag({
+    dragOutside: true,     // Enable dragging outside canvas (default: false)
+    clampWheel: false,     // Other options work as usual
+    mouseButtons: 'all'    // Still respects button configuration
+});
+```
+
+## How it Works
+
+When `dragOutside: true` is enabled:
+
+1. **Normal behavior inside canvas**: Works exactly like before
+2. **Outside canvas**: Uses document-level event listeners to track mouse movement
+3. **Cross-window dragging**: Continues panning even when mouse leaves browser window
+4. **Proper cleanup**: Automatically removes document listeners when drag ends
+
+## Benefits
+
+- **Better UX**: No more frustrating drag interruptions
+- **Small canvases**: Enables large mouse movements for fine control
+- **Interactive overlays**: Doesn't stop when mouse moves over UI elements
+- **Backward compatible**: Default `false` maintains existing behavior
+
+## Demo
+
+The development server demo at `http://localhost:5175` shows `dragOutside` in action.
+Look for the green indicator in the top-right corner!
+
+## Browser Support
+
+Works in all modern browsers that support pointer events (IE11+, all evergreen browsers).

test/drag-outside.js

@@ -0,0 +1,51 @@
+require('./node-shim');
+const assert = require('chai').assert;
+const Viewport = require('../').Viewport;
+
+describe('drag-outside', () => {
+    let viewport;
+
+    beforeEach(() => {
+        viewport = new Viewport();
+    });
+
+    afterEach(() => {
+        viewport.destroy();
+    });
+
+    it('dragOutside option defaults to false', () => {
+        const drag = viewport.drag();
+        assert.isFalse(drag.options.dragOutside);
+    });
+
+    it('dragOutside option can be enabled', () => {
+        const drag = viewport.drag({ dragOutside: true });
+        assert.isTrue(drag.options.dragOutside);
+    });
+
+    it('dragOutside option is included in default options', () => {
+        const drag = viewport.drag({ dragOutside: true });
+        assert.property(drag.options, 'dragOutside');
+        assert.isBoolean(drag.options.dragOutside);
+    });
+
+    it('dragOutside works with other options', () => {
+        const drag = viewport.drag({ 
+            dragOutside: true,
+            clampWheel: true,
+            factor: 2
+        });
+        assert.isTrue(drag.options.dragOutside);
+        assert.isTrue(drag.options.clampWheel);
+        assert.equal(drag.options.factor, 2);
+    });
+
+    it('dragOutside properly sets up internal state', () => {
+        viewport.drag({ dragOutside: true });
+        const drag = viewport.plugins.get('drag');
+        
+        // Check that internal properties are initialized
+        assert.isFalse(drag.isDragOutside);
+        assert.isUndefined(drag.dragOutsideStartPosition);
+    });
+});