docs: add DocumentNavigator development infrastructure and test suite

- Add comprehensive widget plugin infrastructure documentation and workplan
- Include complete DocumentNavigator integration documentation
- Add TDD test suite with 15 comprehensive test cases for DocumentNavigator
- Include widget base classes (Widget, UIWidget) for future development
- Add DocumentNavigator plugin definition following planned architecture
- Include test runner and demo pages for development validation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

markitect/static/js/plugins/document-navigator-plugin.js

@@ -0,0 +1,207 @@
+/**
+ * DocumentNavigator Plugin Definition
+ *
+ * Plugin definition for the Substack-style document navigation widget.
+ * Provides floating table of contents with smooth scrolling and scroll spy.
+ */
+export default {
+    name: 'DocumentNavigator',
+    version: '1.0.0',
+    description: 'Substack-style floating document navigation with table of contents',
+    author: 'Markitect Core',
+    category: 'navigation',
+
+    // Dependencies that must be loaded first
+    dependencies: ['UIWidget'],
+
+    // Mixins to apply (none required for this widget)
+    mixins: [],
+
+    // Lazy load the actual widget class
+    async load() {
+        const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
+        return DocumentNavigator;
+    },
+
+    // Default configuration
+    defaultOptions: {
+        position: 'left',               // 'left' or 'right' side
+        collapsed: true,                // Start in collapsed state
+        autoHide: true,                 // Hide on mobile devices
+        maxHeadingLevel: 3,            // Include H1, H2, H3
+        enableScrollSpy: true,          // Highlight current section
+        smoothScroll: true,             // Smooth scroll to headings
+        animationDuration: 300,         // Animation timing in ms
+        minHeadings: 2,                // Minimum headings to show widget
+        theme: 'default',              // Theme variant
+
+        // Layout options
+        width: '280px',                // Expanded width
+        collapsedWidth: '40px',        // Collapsed width
+        offset: {                      // Position offset
+            top: '80px',
+            side: '20px'
+        },
+
+        // Accessibility
+        enableKeyboard: true,           // Keyboard navigation support
+        ariaLabel: 'Document Navigation'
+    },
+
+    // Plugin lifecycle hooks
+    async onLoad(instance, options) {
+        console.log('DocumentNavigator plugin loaded:', {
+            headings: instance.headings.length,
+            position: options.position,
+            collapsed: options.collapsed
+        });
+
+        // Auto-initialize after load
+        await instance.initialize();
+
+        return instance;
+    },
+
+    async onUnload(instance) {
+        console.log('DocumentNavigator plugin unloading');
+        await instance.destroy();
+    },
+
+    // Feature flags and capabilities
+    capabilities: {
+        draggable: false,              // Not draggable (fixed position)
+        resizable: false,              // Not resizable (fixed width)
+        themeable: true,               // Supports themes
+        persistent: false,             // Rebuilds on page changes
+        responsive: true,              // Responsive behavior
+        keyboard: true,                // Keyboard accessible
+        scrollSpy: true,              // Scroll spy functionality
+        smoothScroll: true            // Smooth scroll navigation
+    },
+
+    // Integration requirements
+    requirements: {
+        container: true,               // Requires container element
+        headings: true,               // Requires document headings
+        scrollable: true              // Requires scrollable content
+    },
+
+    // Event types emitted by this widget
+    events: [
+        'rendered',                   // Widget rendered to DOM
+        'navigate',                   // User navigated to heading
+        'toggle',                     // Widget expanded/collapsed
+        'theme-changed',              // Theme was changed
+        'destroyed'                   // Widget was destroyed
+    ],
+
+    // CSS classes used by this widget
+    cssClasses: [
+        'document-navigator',         // Main widget class
+        'navigator-toggle',           // Toggle button
+        'navigator-list',            // Navigation list
+        'navigator-item',            // Navigation items
+        'navigator-link',            // Navigation links
+        'navigator-header',          // List header
+        'navigator-close',           // Close button
+        'navigator-empty'            // Empty state
+    ],
+
+    // Theme variants
+    themes: {
+        default: {
+            backgroundColor: 'rgba(255, 255, 255, 0.95)',
+            borderColor: '#e1e5e9',
+            textColor: '#333',
+            activeColor: '#1976d2',
+            activeBackground: '#e3f2fd'
+        },
+        dark: {
+            backgroundColor: 'rgba(45, 45, 45, 0.95)',
+            borderColor: '#555',
+            textColor: '#e0e0e0',
+            activeColor: '#64b5f6',
+            activeBackground: '#1e3a8a'
+        },
+        minimal: {
+            backgroundColor: 'rgba(248, 249, 250, 0.90)',
+            borderColor: '#dee2e6',
+            textColor: '#495057',
+            activeColor: '#007bff',
+            activeBackground: '#e7f1ff'
+        }
+    },
+
+    // Usage examples
+    examples: {
+        basic: {
+            description: 'Basic document navigator on the left side',
+            code: `
+                const navigator = await widgetSystem.createWidget('DocumentNavigator');
+                await navigator.show();
+            `
+        },
+        customized: {
+            description: 'Customized navigator with specific options',
+            code: `
+                const navigator = await widgetSystem.createWidget('DocumentNavigator', {
+                    position: 'right',
+                    collapsed: false,
+                    maxHeadingLevel: 4,
+                    theme: 'dark'
+                });
+                await navigator.show();
+            `
+        },
+        withContainer: {
+            description: 'Navigator for specific container content',
+            code: `
+                const container = document.getElementById('article-content');
+                const navigator = await widgetSystem.createWidget('DocumentNavigator', {
+                    container: container,
+                    minHeadings: 1
+                });
+                await navigator.show();
+            `
+        }
+    },
+
+    // Development and testing helpers
+    dev: {
+        testHeadingStructure() {
+            // Helper to create test content with headings
+            const testContent = `
+                <h1>Chapter 1: Introduction</h1>
+                <p>Lorem ipsum content...</p>
+                <h2>Section 1.1: Overview</h2>
+                <h3>Subsection 1.1.1: Details</h3>
+                <h2>Section 1.2: Implementation</h2>
+                <h1>Chapter 2: Advanced Topics</h1>
+                <h2>Section 2.1: Performance</h2>
+            `;
+
+            const container = document.createElement('div');
+            container.innerHTML = testContent;
+            container.style.cssText = 'height: 2000px; padding: 2rem;';
+            document.body.appendChild(container);
+
+            return container;
+        },
+
+        async createTestInstance(options = {}) {
+            // Helper to create test instance with sample content
+            const container = this.testHeadingStructure();
+
+            const navigator = new (await this.load())({
+                container,
+                collapsed: false,
+                ...options
+            });
+
+            await navigator.initialize();
+            await navigator.render();
+
+            return { navigator, container };
+        }
+    }
+};