@eyeglass/inspector 0.1.0

package/dist/fiber-walker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * React Fiber Walker - extracts component info from React DevTools internals
+ */
+export interface FrameworkInfo {
+    name: 'react' | 'vue' | 'svelte' | 'vanilla';
+    componentName?: string;
+    filePath?: string;
+    lineNumber?: number;
+    props?: Record<string, unknown>;
+    ancestry?: string[];
+}
+/**
+ * Extract framework information from a DOM element
+ */
+export declare function extractFrameworkInfo(element: Element): FrameworkInfo;

package/dist/fiber-walker.js

@@ -0,0 +1,223 @@
+/**
+ * React Fiber Walker - extracts component info from React DevTools internals
+ */
+// Fiber tag constants
+const FunctionComponent = 0;
+const ClassComponent = 1;
+const ForwardRef = 11;
+const MemoComponent = 14;
+const SimpleMemoComponent = 15;
+const COMPONENT_TAGS = new Set([
+    FunctionComponent,
+    ClassComponent,
+    ForwardRef,
+    MemoComponent,
+    SimpleMemoComponent,
+]);
+/**
+ * Find the React Fiber attached to a DOM element
+ */
+function getFiberFromElement(element) {
+    const keys = Object.keys(element);
+    const fiberKey = keys.find((k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'));
+    if (!fiberKey)
+        return null;
+    return element[fiberKey];
+}
+/**
+ * Check if a fiber is a user-defined component (not built-in React internals)
+ */
+function isUserComponent(fiber) {
+    if (!COMPONENT_TAGS.has(fiber.tag) || typeof fiber.type !== 'function') {
+        return false;
+    }
+    const name = fiber.type.displayName || fiber.type.name || '';
+    // Skip built-in React components (Context.Provider, StrictMode, etc.)
+    if (!name || name.startsWith('Context') || name.endsWith('Provider') || name === 'StrictMode') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Get component name from fiber
+ */
+function getComponentName(fiber) {
+    return fiber.type.displayName || fiber.type.name || undefined;
+}
+/**
+ * Walk up the fiber tree to find the nearest user-defined component
+ */
+function findComponentFiber(fiber) {
+    let current = fiber;
+    while (current) {
+        if (isUserComponent(current)) {
+            return current;
+        }
+        current = current.return;
+    }
+    return null;
+}
+/**
+ * Collect all parent component names by walking up the fiber tree
+ */
+function collectAncestry(fiber) {
+    const ancestry = [];
+    let current = fiber;
+    while (current) {
+        if (isUserComponent(current)) {
+            const name = getComponentName(current);
+            if (name) {
+                ancestry.push(name);
+            }
+        }
+        current = current.return;
+    }
+    return ancestry;
+}
+/**
+ * Get safe props (primitives only, no functions/objects)
+ */
+function getSafeProps(props) {
+    if (!props)
+        return undefined;
+    const safe = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (key === 'children')
+            continue;
+        const type = typeof value;
+        if (type === 'string' || type === 'number' || type === 'boolean' || value === null) {
+            safe[key] = value;
+        }
+    }
+    return Object.keys(safe).length > 0 ? safe : undefined;
+}
+/**
+ * Detect Vue component
+ */
+function detectVue(element) {
+    // Vue 2
+    const vueInstance = element.__vue__;
+    if (vueInstance) {
+        const componentName = vueInstance.$options?.name || vueInstance.$options?._componentTag;
+        return {
+            name: 'vue',
+            componentName,
+        };
+    }
+    // Vue 3 - check for any __vue* property
+    const keys = Object.keys(element);
+    const vueKey = keys.find((k) => k.startsWith('__vue'));
+    if (vueKey) {
+        const vnode = element[vueKey];
+        // Try to get component info from vnode
+        if (vnode) {
+            // Walk up to find component instance
+            let instance = vnode;
+            let componentName;
+            let props;
+            // Check various Vue 3 internal structures
+            if (instance?.type?.name) {
+                componentName = instance.type.name;
+            }
+            else if (instance?.type?.__name) {
+                componentName = instance.type.__name;
+            }
+            else if (instance?.component?.type?.name) {
+                componentName = instance.component.type.name;
+            }
+            else if (instance?.component?.type?.__name) {
+                componentName = instance.component.type.__name;
+            }
+            // Try to get props
+            const rawProps = instance?.props || instance?.component?.props;
+            if (rawProps) {
+                props = getSafeProps(rawProps);
+            }
+            // Try to get file info from __file
+            let filePath;
+            if (instance?.type?.__file) {
+                filePath = instance.type.__file;
+            }
+            else if (instance?.component?.type?.__file) {
+                filePath = instance.component.type.__file;
+            }
+            return {
+                name: 'vue',
+                componentName,
+                filePath,
+                props,
+            };
+        }
+        return { name: 'vue' };
+    }
+    return null;
+}
+/**
+ * Detect Svelte component
+ */
+function detectSvelte(element) {
+    const keys = Object.keys(element);
+    const svelteKey = keys.find((k) => k.startsWith('__svelte'));
+    if (svelteKey) {
+        const svelteData = element[svelteKey];
+        // Try to extract component info from Svelte internals
+        let componentName;
+        // Svelte 5 uses different structure
+        if (svelteData?.constructor?.name && svelteData.constructor.name !== 'Object') {
+            componentName = svelteData.constructor.name;
+        }
+        // Check for component context
+        if (!componentName && svelteData?.$$?.ctx) {
+            // Svelte 4 structure
+            const ctx = svelteData.$$.ctx;
+            if (ctx?.constructor?.name && ctx.constructor.name !== 'Object') {
+                componentName = ctx.constructor.name;
+            }
+        }
+        return {
+            name: 'svelte',
+            componentName,
+        };
+    }
+    return null;
+}
+/**
+ * Extract framework information from a DOM element
+ */
+export function extractFrameworkInfo(element) {
+    // Try React first
+    const fiber = getFiberFromElement(element);
+    if (fiber) {
+        const componentFiber = findComponentFiber(fiber);
+        if (componentFiber) {
+            const componentName = getComponentName(componentFiber);
+            const debugSource = componentFiber._debugSource;
+            const ancestry = collectAncestry(componentFiber);
+            return {
+                name: 'react',
+                componentName,
+                filePath: debugSource?.fileName,
+                lineNumber: debugSource?.lineNumber,
+                props: getSafeProps(componentFiber.memoizedProps),
+                ancestry: ancestry.length > 0 ? ancestry : undefined,
+            };
+        }
+        // React element but no user component found (just DOM nodes)
+        // Still try to get ancestry from the fiber
+        const ancestry = collectAncestry(fiber);
+        return {
+            name: 'react',
+            ancestry: ancestry.length > 0 ? ancestry : undefined,
+        };
+    }
+    // Try Vue
+    const vueInfo = detectVue(element);
+    if (vueInfo)
+        return vueInfo;
+    // Try Svelte
+    const svelteInfo = detectSvelte(element);
+    if (svelteInfo)
+        return svelteInfo;
+    // Vanilla fallback
+    return { name: 'vanilla' };
+}

package/dist/fiber-walker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fiber-walker.test.js

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { extractFrameworkInfo } from './fiber-walker.js';
+// Helper to create a mock function with a displayName
+function createMockComponent(name) {
+    const fn = function () { };
+    fn.displayName = name;
+    return fn;
+}
+describe('extractFrameworkInfo', () => {
+    beforeEach(() => {
+        document.body.innerHTML = '';
+    });
+    describe('vanilla detection', () => {
+        it('should return vanilla for plain DOM elements', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('vanilla');
+            expect(info.componentName).toBeUndefined();
+            expect(info.filePath).toBeUndefined();
+        });
+    });
+    describe('React detection', () => {
+        it('should detect React from __reactFiber$ key', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            // Mock React fiber structure
+            const mockFiber = {
+                tag: 0, // FunctionComponent
+                type: createMockComponent('MyComponent'),
+                return: null,
+                _debugSource: {
+                    fileName: 'src/components/MyComponent.tsx',
+                    lineNumber: 42,
+                },
+                memoizedProps: {
+                    className: 'test',
+                    onClick: () => { },
+                    isActive: true,
+                },
+            };
+            div['__reactFiber$abc123'] = mockFiber;
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('react');
+            expect(info.componentName).toBe('MyComponent');
+            expect(info.filePath).toBe('src/components/MyComponent.tsx');
+            expect(info.lineNumber).toBe(42);
+        });
+        it('should detect React from __reactInternalInstance$ key', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            const mockFiber = {
+                tag: 0,
+                type: createMockComponent('Button'),
+                return: null,
+            };
+            div['__reactInternalInstance$xyz789'] = mockFiber;
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('react');
+            expect(info.componentName).toBe('Button');
+        });
+        it('should extract safe props (primitives only)', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            const mockFiber = {
+                tag: 0,
+                type: createMockComponent('Card'),
+                return: null,
+                memoizedProps: {
+                    title: 'Hello',
+                    count: 42,
+                    isOpen: true,
+                    data: null,
+                    children: ['some', 'children'],
+                    onClick: () => { },
+                    config: { nested: 'object' },
+                },
+            };
+            div['__reactFiber$test'] = mockFiber;
+            const info = extractFrameworkInfo(div);
+            expect(info.props).toEqual({
+                title: 'Hello',
+                count: 42,
+                isOpen: true,
+                data: null,
+            });
+            // Should not include children, functions, or objects
+            expect(info.props?.children).toBeUndefined();
+            expect(info.props?.onClick).toBeUndefined();
+            expect(info.props?.config).toBeUndefined();
+        });
+        it('should walk up fiber tree to find component', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            // Simulate a DOM fiber with component parents
+            const parentFiber = {
+                tag: 0,
+                type: createMockComponent('ParentComponent'),
+                return: null,
+            };
+            const domFiber = {
+                tag: 5, // HostComponent (div)
+                type: 'div',
+                return: parentFiber,
+            };
+            div['__reactFiber$test'] = domFiber;
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('react');
+            expect(info.componentName).toBe('ParentComponent');
+        });
+        it('should collect ancestry chain', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            const appFiber = {
+                tag: 0,
+                type: createMockComponent('App'),
+                return: null,
+            };
+            const cardFiber = {
+                tag: 0,
+                type: createMockComponent('Card'),
+                return: appFiber,
+            };
+            const buttonFiber = {
+                tag: 0,
+                type: createMockComponent('Button'),
+                return: cardFiber,
+            };
+            div['__reactFiber$test'] = buttonFiber;
+            const info = extractFrameworkInfo(div);
+            expect(info.ancestry).toEqual(['Button', 'Card', 'App']);
+        });
+        it('should skip Context.Provider and similar internal components', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            const appFiber = {
+                tag: 0,
+                type: createMockComponent('App'),
+                return: null,
+            };
+            const providerFiber = {
+                tag: 0,
+                type: createMockComponent('ThemeProvider'),
+                return: appFiber,
+            };
+            const contextFiber = {
+                tag: 0,
+                type: createMockComponent('Context.Consumer'),
+                return: providerFiber,
+            };
+            const buttonFiber = {
+                tag: 0,
+                type: createMockComponent('Button'),
+                return: contextFiber,
+            };
+            div['__reactFiber$test'] = buttonFiber;
+            const info = extractFrameworkInfo(div);
+            // The nearest user component should be Button
+            expect(info.componentName).toBe('Button');
+        });
+    });
+    describe('Vue detection', () => {
+        it('should detect Vue 2 from __vue__', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            div.__vue__ = {
+                $options: {
+                    name: 'MyVueComponent',
+                },
+            };
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('vue');
+            expect(info.componentName).toBe('MyVueComponent');
+        });
+        it('should detect Vue 3 from __vueParentComponent', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            div.__vueParentComponent = {
+                type: {
+                    name: 'VueThreeComponent',
+                    __file: 'src/components/VueThreeComponent.vue',
+                },
+                props: {
+                    message: 'Hello',
+                    count: 5,
+                },
+            };
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('vue');
+            expect(info.componentName).toBe('VueThreeComponent');
+            expect(info.filePath).toBe('src/components/VueThreeComponent.vue');
+            expect(info.props).toEqual({
+                message: 'Hello',
+                count: 5,
+            });
+        });
+        it('should detect Vue 3 with __name', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            div.__vueParentComponent = {
+                type: {
+                    __name: 'SetupScriptComponent',
+                },
+            };
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('vue');
+            expect(info.componentName).toBe('SetupScriptComponent');
+        });
+    });
+    describe('Svelte detection', () => {
+        it('should detect Svelte from __svelte key', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            div.__svelte_component = {
+                constructor: {
+                    name: 'SvelteButton',
+                },
+            };
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('svelte');
+        });
+        it('should extract Svelte component name', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            class MySvelteComponent {
+            }
+            div.__svelte_component = new MySvelteComponent();
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('svelte');
+            expect(info.componentName).toBe('MySvelteComponent');
+        });
+    });
+    describe('framework priority', () => {
+        it('should prefer React over Vue if both are present', () => {
+            const div = document.createElement('div');
+            document.body.appendChild(div);
+            // Add both React and Vue markers
+            const mockFiber = {
+                tag: 0,
+                type: createMockComponent('ReactComp'),
+                return: null,
+            };
+            div['__reactFiber$test'] = mockFiber;
+            div.__vue__ = {
+                $options: { name: 'VueComp' },
+            };
+            const info = extractFrameworkInfo(div);
+            expect(info.name).toBe('react');
+            expect(info.componentName).toBe('ReactComp');
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @eyeglass/inspector - Browser-side inspection web component
+ *
+ * Usage:
+ *   import '@eyeglass/inspector';
+ *   // Or inject via script tag
+ *
+ * This automatically registers the <eyeglass-inspector> custom element.
+ */
+export { EyeglassInspector } from './inspector.js';
+export { captureSnapshot } from './snapshot.js';
+export { extractFrameworkInfo } from './fiber-walker.js';
+export type { FrameworkInfo } from './fiber-walker.js';
+/**
+ * Initialize the inspector by appending it to the document
+ */
+export declare function initInspector(): void;

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @eyeglass/inspector - Browser-side inspection web component
+ *
+ * Usage:
+ *   import '@eyeglass/inspector';
+ *   // Or inject via script tag
+ *
+ * This automatically registers the <eyeglass-inspector> custom element.
+ */
+export { EyeglassInspector } from './inspector.js';
+export { captureSnapshot } from './snapshot.js';
+export { extractFrameworkInfo } from './fiber-walker.js';
+/**
+ * Initialize the inspector by appending it to the document
+ */
+export function initInspector() {
+    if (document.querySelector('eyeglass-inspector')) {
+        console.warn('[eyeglass] Inspector already initialized');
+        return;
+    }
+    const inspector = document.createElement('eyeglass-inspector');
+    document.body.appendChild(inspector);
+    console.log('[eyeglass] Inspector initialized. Hover over elements and click to annotate.');
+}
+// Auto-initialize when imported in a browser context
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initInspector);
+    }
+    else {
+        initInspector();
+    }
+}

package/dist/inspector.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Eyeglass Inspector - Glass UI for visual element inspection
+ */
+export declare class EyeglassInspector extends HTMLElement {
+    private shadow;
+    private highlight;
+    private panel;
+    private toast;
+    private hub;
+    private currentElement;
+    private currentSnapshot;
+    private interactionId;
+    private frozen;
+    private eventSource;
+    private throttleTimeout;
+    private mode;
+    private activityEvents;
+    private currentStatus;
+    private hubExpanded;
+    private inspectorEnabled;
+    private history;
+    private isDragging;
+    private dragOffset;
+    private customPanelPosition;
+    private multiSelectMode;
+    private selectedElements;
+    private selectedSnapshots;
+    private multiSelectHighlights;
+    private submittedSnapshots;
+    private static readonly MAX_SELECTION;
+    private cursorStyleElement;
+    private scrollTimeout;
+    constructor();
+    connectedCallback(): void;
+    private saveSession;
+    private restoreSession;
+    private showResultToast;
+    private hideToast;
+    private loadHistory;
+    private saveHistory;
+    private addToHistory;
+    private updateHistoryStatus;
+    private renderHub;
+    private requestUndo;
+    disconnectedCallback(): void;
+    private connectSSE;
+    private handleActivityEvent;
+    private handleMouseMove;
+    private handleClick;
+    private handleKeyDown;
+    private handleScroll;
+    private disableHighlightTransitions;
+    private enableHighlightTransitions;
+    private updateMultiSelectHighlightPositions;
+    private handlePanelDragStart;
+    private handlePanelDrag;
+    private handlePanelDragEnd;
+    private showHighlight;
+    private hideHighlight;
+    private freeze;
+    private enterMultiSelectMode;
+    private toggleInSelection;
+    private removeFromSelection;
+    private exitMultiSelectMode;
+    private renderMultiSelectHighlights;
+    private clearMultiSelectHighlights;
+    private unfreeze;
+    private renderPanel;
+    private renderInputMode;
+    private renderActivityMode;
+    private renderActivityFeed;
+    private renderStatusItem;
+    private renderThoughtItem;
+    private renderActionItem;
+    private renderQuestionItem;
+    private getUserNote;
+    private getStatusText;
+    private hidePanel;
+    private submit;
+    private submitAnswer;
+    private escapeHtml;
+    private updateCursor;
+}