Hopiu/bowser
1
0
Fork 0
mirror of https://github.com/Hopiu/bowser.git synced 2026-03-16 19:10:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Removed old documentation files

Browse source
This commit is contained in:
Benedikt Willi 2026-01-12 09:16:23 +01:00
parent 99a3a4c145
commit 4b3ba9144d
8 changed files with 138 additions and 744 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

146
FEATURE_DOM_GRAPH.md
View file

@ -1,146 +0,0 @@
# DOM Visualization Feature - Implementation Summary
## Overview
Added a keyboard shortcut (Ctrl+Shift+D) to generate and visualize the DOM tree of the current tab as a graph.
## Files Created
### Core Implementation
- **src/debug/__init__.py** - Debug utilities package
- **src/debug/dom_graph.py** - DOM graph generation and visualization
- `generate_dot_graph()` - Generates Graphviz DOT format
- `save_dom_graph()` - Saves DOT file
- `render_dom_graph_to_svg()` - Renders to SVG (requires graphviz)
- `print_dom_tree()` - Text tree representation
### Tests
- **tests/test_dom_graph.py** - Comprehensive test suite (10 tests, all passing)
- Tests graph generation, coloring, escaping, truncation
- Tests tree printing with proper indentation
- Tests depth limiting and attribute handling
### Documentation
- **docs/DOM_VISUALIZATION.md** - Feature documentation
- **test_dom.html** - Example test page
- Updated **README.md** with keyboard shortcuts section
## Implementation Details
### Browser Integration (src/browser/chrome.py)
1. **Keyboard Shortcut Setup**
- Added `_setup_keyboard_shortcuts()` method
- Registers GTK EventControllerKey for key presses
- Listens for Ctrl+Shift+D combination
2. **DOM Graph Handler**
- Added `_on_key_pressed()` callback
- Added `_show_dom_graph()` method that:
- Gets current tab's DOM document
- Generates graph in DOT format
- Attempts SVG rendering (if graphviz installed)
- Falls back to DOT file
- Prints tree to console
- Shows info dialog with result
3. **UI Feedback**
- Added `_show_info_dialog()` for user notifications
- Opens generated SVG automatically with xdg-open
### Graph Features
**Color Coding:**
- Light green: `<html>`, `<body>`
- Light yellow: Headings (`<h1>`-`<h6>`)
- Light gray: Block elements (`<div>`, `<p>`, `<span>`)
- Light cyan: Lists (`<ul>`, `<ol>`, `<li>`)
- Light pink: Interactive (`<a>`, `<button>`)
- Light blue: Text nodes
- White: Other elements
**Node Information:**
- Element nodes show tag name and up to 3 attributes
- Text nodes show content preview (max 50 chars)
- Hierarchical edges show parent-child relationships
**Output:**
- Files saved to `~/.cache/bowser/`
- `dom_graph.svg` - Visual graph (if graphviz available)
- `dom_graph.dot` - DOT format definition
- Console output shows full tree structure
## Usage
1. Open any page in Bowser
2. Press **Ctrl+Shift+D**
3. View results:
- Console: Text tree structure
- File browser: Opens SVG (if graphviz installed)
- Dialog: Shows file location
## Testing
All tests passing:
```bash
uv run pytest tests/test_dom_graph.py -v
# 10 passed in 0.11s
```
Test coverage:
- Empty document handling
- Simple HTML structures
- Nested elements
- Attributes rendering
- Text escaping
- Long text truncation
- Color coding
- Tree indentation
- Depth limiting
## Dependencies
**Required:**
- Python standard library
- Existing Bowser dependencies (GTK, Skia)
**Optional:**
- Graphviz (`dot` command) for SVG rendering
- Install: `sudo apt install graphviz`
- Gracefully falls back to DOT file if not available
## Example Output
For this HTML:
```html
<html>
<body>
<h1>Title</h1>
<p>Content</p>
</body>
</html>
```
Generates a graph showing:
- Root `html` node (green)
- `body` child (green)
- `h1` child (yellow)
- "Title" text (blue)
- `p` child (gray)
- "Content" text (blue)
## Benefits
1. **Debugging Aid**: Visually inspect parsed DOM structure
2. **Learning Tool**: Understand how HTML is parsed
3. **Structure Validation**: Verify element nesting and hierarchy
4. **Development**: Quickly check if DOM building works correctly
## Future Enhancements
Potential improvements:
- Add CSS selector highlighting
- Show computed styles on nodes
- Interactive graph (clickable nodes)
- Export to different formats (PNG, PDF)
- Side-by-side HTML source comparison
- DOM mutation tracking

80
QUICKSTART_DOM_GRAPH.md
View file

@ -1,80 +0,0 @@
# DOM Graph Visualization - Quick Reference
## What is it?
A debugging tool that visualizes the Document Object Model (DOM) tree of the currently loaded web page as a graph.
## How to use it?
Press **Ctrl+Shift+D** while viewing any page in Bowser.
## What you get
### 1. Console Output
```
DOM TREE STRUCTURE:
====================
<html>
<body>
<h1>
Text: 'Page Title'
<p>
Text: 'Page content...'
```
### 2. New Browser Tab
- Automatically opens with the visualization
- Clean, dark-themed interface
- Color legend explaining node colors
- Interactive SVG graph (if Graphviz installed)
- DOT format view with installation instructions (without Graphviz)
### 3. Graph File
Saved to `~/.cache/bowser/dom_graph.svg` (or `.dot` without Graphviz)
## Node Colors
| Color | Elements |
|-------|----------|
| 🟢 Light Green | `<html>`, `<body>` |
| 🟡 Light Yellow | `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>` |
| ⚪ Light Gray | `<div>`, `<p>`, `<span>` |
| 🔵 Light Cyan | `<ul>`, `<ol>`, `<li>` |
| 🔴 Light Pink | `<a>`, `<button>` |
| 🔵 Light Blue | Text nodes |
| ⚪ White | Other elements |
## Installation (Optional)
For visual graphs, install Graphviz:
```bash
sudo apt install graphviz
```
Without it, you'll get a `.dot` file that you can:
- View with any text editor
- Render online at http://webgraphviz.com
- Render manually: `dot -Tsvg dom_graph.dot -o output.svg`
## Test it!
1. Load the test page:
```bash
uv run bowser file://$(pwd)/test_dom.html
```
2. Press **Ctrl+Shift+D**
3. View the generated graph!
## Files
- **Implementation**: `src/debug/dom_graph.py`
- **Tests**: `tests/test_dom_graph.py` (10/10 passing)
- **Docs**: `docs/DOM_VISUALIZATION.md`
- **Example**: `test_dom.html`
## Benefits
- 🔍 **Debug**: Quickly inspect DOM structure
- 📚 **Learn**: Understand HTML parsing
- ✅ **Validate**: Check element hierarchy
- 🎨 **Visualize**: See the tree structure clearly

199
README.md
View file

@ -1,97 +1,158 @@
# Bowser — Educational Web Browser
A custom web browser built from scratch following the [browser.engineering](https://browser.engineering/) curriculum.
A custom web browser built from scratch following the [browser.engineering](https://browser.engineering/) curriculum. Features a clean architecture with Skia-based rendering, GTK 4/Adwaita UI, and proper separation of concerns.
**Status**: Early scaffolding phase (M0)
**Status**: Milestone 2 - Basic HTML rendering with text layout
## Building
## Features
### Prerequisites
- Python 3.11+
- GTK 4 development libraries (Debian: `libgtk-4-dev libgtk-4-1`)
- Skia-Python (`skia-python`): `pip install skia-python`
- PyGObject (`PyGObject`): `pip install PyGObject`
- Graphviz (optional, for DOM visualization): `sudo apt install graphviz`
- **Adwaita Tab Bar** - Modern GNOME-style tab management
- **Skia Rendering** - Hardware-accelerated 2D graphics
- **Text Layout** - Word wrapping, character-level selection
- **DOM Parsing** - HTML parsing with proper tree structure
- **Debug Mode** - Visual layout debugging with FPS counter
- **DOM Visualization** - Generate visual graphs of page structure
## Quick Start
### Setup
```bash
# Install dependencies and run
uv sync
uv run bowser
# Browse a website
uv run bowser example.com
# Enable debug mode (shows FPS, layout boxes)
uv run bowser example.com --debug
```
## Usage
## Keyboard Shortcuts
### Keyboard Shortcuts
- **Ctrl+Shift+D**: Generate and visualize DOM tree graph of current page
- Opens visualization in a new browser tab
- Displays interactive SVG graph (if Graphviz installed)
- Falls back to DOT format if Graphviz not available
- Prints tree structure to console
| Shortcut | Action |
|----------|--------|
| `Ctrl+T` | New tab |
| `Ctrl+W` | Close tab |
| `Ctrl+L` | Focus address bar |
| `Ctrl+Shift+D` | Generate DOM visualization |
| `Ctrl+Shift+O` | Toggle debug mode |
### Testing
Run the test suite:
```bash
# Install dev dependencies
uv sync --extra dev
# Run all tests
uv run pytest
# Run with verbose output
uv run pytest -v
# Run with coverage report
uv run pytest --cov=src --cov-report=html
# Run specific test file
uv run pytest tests/test_browser.py
```
### Development
```bash
# Format code
uv run black src tests
# Lint code
uv run ruff check src tests
# Type check
uv run mypy src
```
## Project Structure
## Architecture
```
bowser/
├── src/
│ ├── network/ # URL parsing, HTTP, cookies
│ ├── parser/ # HTML & CSS parsers
│ ├── layout/ # Block/inline/embedded layout
│ ├── render/ # Paint commands, fonts, compositing
│ ├── script/ # JavaScript integration
│ ├── browser/ # Tab/frame/chrome orchestration
│ └── accessibility/ # A11y tree and screen reader
├── assets/ # Stylesheets, images
├── tests/ # Unit tests
├── pyproject.toml # Dependencies & build config
└── main.py # Entry point
│ ├── browser/ # Browser UI (chrome.py, tab.py)
│ │ ├── browser.py # Application orchestration
│ │ ├── chrome.py # GTK/Adwaita window, tab bar, address bar
│ │ └── tab.py # Tab and frame management
│ │
│ ├── parser/ # Document parsing
│ │ ├── html.py # HTML → DOM tree (Element, Text nodes)
│ │ └── css.py # CSS parsing (stub)
│ │
│ ├── layout/ # Layout calculation
│ │ ├── document.py # DocumentLayout - full page layout
│ │ ├── block.py # BlockLayout, LineLayout - block elements
│ │ └── inline.py # TextLayout, InlineLayout - text runs
│ │
│ ├── render/ # Painting & rendering
│ │ ├── pipeline.py # RenderPipeline - coordinates layout/paint
│ │ ├── fonts.py # FontCache - Skia font management
│ │ ├── paint.py # DisplayList, DrawText, DrawRect
│ │ └── composite.py # Layer compositing
│ │
│ ├── network/ # Networking
│ │ ├── http.py # HTTP client with redirects
│ │ ├── url.py # URL parsing and normalization
│ │ └── cookies.py # Cookie management
│ │
│ ├── debug/ # Development tools
│ │ └── dom_graph.py # DOM tree visualization
│ │
│ └── templates.py # Page templates (start page, errors)
│
├── tests/ # Test suite
└── main.py # Entry point
```
## Development Milestones
### Design Principles
- [ ] **M0**: Project scaffold ✅
- [ ] **M1**: Display "Hello World" in GTK window with manual URL fetch & paint
- [ ] **M2**: Render plain HTML with text wrapping
- [ ] **M3**: Parse and apply basic CSS
**Separation of Concerns:**
- `parser/` - Pure DOM data structures (Element, Text)
- `layout/` - Position and size calculations (x, y, width, height)
- `render/` - Drawing commands and font management
- `browser/` - UI only (tabs, address bar, event handling)
**Key Classes:**
| Class | Package | Responsibility |
|-------|---------|----------------|
| `Element`, `Text` | parser | DOM tree nodes |
| `DocumentLayout` | layout | Page layout with line positioning |
| `LayoutLine`, `LayoutBlock` | layout | Positioned text with bounding boxes |
| `RenderPipeline` | render | Coordinates layout → paint |
| `FontCache` | render | Skia font caching |
| `Chrome` | browser | GTK window, delegates to RenderPipeline |
## Development
### Prerequisites
- Python 3.11+
- GTK 4 (`libgtk-4-dev libgtk-4-1`)
- libadwaita (`libadwaita-1-dev`)
- Graphviz (optional, for DOM visualization)
```bash
# Debian/Ubuntu
sudo apt install libgtk-4-dev libadwaita-1-dev graphviz
```
### Testing
```bash
uv run pytest # Run all tests
uv run pytest -v # Verbose output
uv run pytest --cov=src # Coverage report
```
### Code Quality
```bash
uv run black src tests # Format code
uv run ruff check src # Lint
uv run mypy src # Type check
```
## Debug Mode
Enable with `--debug` flag or press `Ctrl+Shift+O` at runtime.
Shows:
- **FPS counter** with frame timing breakdown
- **Layout boxes** colored by element type:
- Red: Block elements (`<div>`, `<p>`)
- Blue: Inline elements (`<span>`, `<a>`)
- Green: List items (`<li>`)
## Milestones
- [x] **M0**: Project scaffold
- [x] **M1**: GTK window with Skia rendering
- [x] **M2**: HTML parsing and text layout
- [ ] **M3**: CSS parsing and styling
- [ ] **M4**: Clickable links and navigation
- [ ] **M5**: Form input and submission
- [ ] **M6**: JavaScript execution (embed QuickJS)
- [ ] **M6**: JavaScript execution
- [ ] **M7**: Event handling
- [ ] **M8**: Images and iframes
- [ ] **M9**: Animations and visual effects
- [ ] **M10**: Accessibility and keyboard navigation
## References
- [Web Browser Engineering](https://browser.engineering/) — O'Reilly book
- [Let's Build a Browser Engine](https://limpet.net/mbrubeck/2014/08/08/toy-layout-engine-1.html) — Matt Brubeck's Rust tutorial
- [Let's Build a Browser Engine](https://limpet.net/mbrubeck/2014/08/08/toy-layout-engine-1.html) — Matt Brubeck
## License
MIT

152
UPDATE_DOM_TAB.md
View file

@ -1,152 +0,0 @@
# DOM Graph in Browser Tab - Update Summary
## What Changed
The DOM visualization feature now displays the graph **in a new browser tab** instead of opening an external application.
## Key Improvements
### Before
- Pressed Ctrl+Shift+D
- Graph opened in external SVG viewer (xdg-open)
- Required switching between applications
- Less integrated experience
### After
- Press Ctrl+Shift+D
- Graph opens in new browser tab automatically
- Stay within Bowser
- Beautiful dark-themed interface
- Built-in color legend
- Consistent with browser workflow
## Implementation Changes
### 1. Modified chrome.py
**`_show_dom_graph()` method**:
- Removed external `xdg-open` call
- Now calls `browser.new_tab("about:dom-graph?path=...")`
- Passes graph file path as URL parameter
### 2. Modified tab.py
**`Frame.load()` method**:
- Added handler for `about:dom-graph` URLs
- Parses query parameter to get graph file path
- Calls `render_dom_graph_page()` to generate HTML
- Parses result into DOM
### 3. Modified templates.py
**New function: `render_dom_graph_page()`**:
- Takes graph file path as parameter
- Detects SVG vs DOT format
- Reads file content
- Renders using `dom_graph.html` template
- Handles errors gracefully
### 4. New Template
**`assets/pages/dom_graph.html`**:
- Dark-themed, modern interface
- Header with title and file path
- Color legend for SVG graphs
- Inline SVG embedding
- DOT format display with syntax highlighting
- Installation instructions for Graphviz
- Responsive layout
### 5. New Tests
**`tests/test_dom_graph_page.py`**:
- Tests SVG rendering
- Tests DOT rendering
- Tests error handling
- Tests legend presence
- All 4 tests passing ✓
## Features
### Visual Design
- 🎨 Dark theme (#1e1e1e background)
- 🎯 VS Code-inspired color scheme
- 📊 Inline SVG rendering
- 🎨 Color-coded legend
- 📝 Monospace font for code
- 🔲 Card-based layout
### User Experience
- ⚡ Automatic tab opening
- 🎯 No application switching
- 📍 Clear file path display
- 💡 Helpful installation hints
- 🔄 Reminder to use Ctrl+Shift+D
### Error Handling
- ✅ Missing file detection
- ✅ Read error handling
- ✅ Graceful degradation
- ✅ Clear error messages
## URL Scheme
New special URL: `about:dom-graph?path=/path/to/graph.svg`
Query parameters:
- `path`: Absolute path to graph file (SVG or DOT)
## File Structure
```
src/
browser/
chrome.py # Opens new tab with about:dom-graph
tab.py # Handles about:dom-graph URL
templates.py # Renders graph page
debug/
dom_graph.py # Generates graph files (unchanged)
assets/pages/
dom_graph.html # New template for graph display
tests/
test_dom_graph.py # Graph generation tests (10 tests)
test_dom_graph_page.py # Page rendering tests (4 tests)
```
## Testing Results
```
tests/test_html_parsing.py - 7/7 passed ✓
tests/test_dom_graph.py - 10/10 passed ✓
tests/test_dom_graph_page.py - 4/4 passed ✓
tests/test_templates.py - 7/7 passed ✓
--------------------------------
Total: 28/28 passed ✓
```
## Usage Example
1. Browse to any page
2. Press **Ctrl+Shift+D**
3. New tab opens with:
- Header: "🌳 DOM Tree Visualization"
- File path shown
- Color legend
- Interactive SVG graph OR
- DOT format with install instructions
4. Console shows text tree structure
## Benefits
✅ **Better UX**: No context switching
✅ **Consistent**: All in browser
✅ **Informative**: Built-in legend and hints
✅ **Beautiful**: Modern, dark theme
✅ **Accessible**: Clear labels and structure
✅ **Flexible**: Works with/without Graphviz
✅ **Tested**: Comprehensive test coverage
## Backward Compatibility
- Graph files still saved to `~/.cache/bowser/`
- Console output unchanged
- Same keyboard shortcut (Ctrl+Shift+D)
- Same file formats (SVG/DOT)
- Existing functionality preserved

157
docs/DOM_GRAPH_UX.md
View file

@ -1,157 +0,0 @@
# DOM Graph Visualization - User Experience
## What You'll See
When you press **Ctrl+Shift+D**, a new tab automatically opens with this view:
```
┌─────────────────────────────────────────────────────────────────┐
│ 🌳 DOM Tree Visualization │
│ Source: /home/user/.cache/bowser/dom_graph.svg │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Color Legend: │
│ ┌─────────┬──────────────────────────────────────────────┐ │
│ │ 🟢 │ <html>, <body> │ │
│ │ 🟡 │ Headings (h1-h6) │ │
│ │ ⚪ │ Block elements │ │
│ │ 🔵 │ Lists (ul, ol, li) │ │
│ │ 🔴 │ Interactive (a, button) │ │
│ │ 🔵 │ Text nodes │ │
│ └─────────┴──────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ [Visual DOM Graph Here] │ │
│ │ │ │
│ │ html ──┬── body ──┬── h1 ── "Title" │ │
│ │ │ │ │
│ │ ├── p ── "Content" │ │
│ │ │ │ │
│ │ └── ul ──┬── li ── "Item 1" │ │
│ │ └── li ── "Item 2" │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Bowser Browser • DOM Graph Visualization • Ctrl+Shift+D │
└─────────────────────────────────────────────────────────────────┘
```
## Interface Elements
### Header (Dark Gray)
- 🌳 Title with icon
- File path showing where graph is saved
- Clean, minimal design
### Color Legend
- Explains what each color means
- 6 different node types
- Easy reference while viewing graph
### Graph Display
**With Graphviz (SVG):**
- Beautiful vector graphics
- Zoomable/scalable
- Clean node layout
- Clear hierarchy
**Without Graphviz (DOT):**
- Installation instructions
- Raw DOT format shown
- Helpful hints for rendering
### Footer (Dark Gray)
- Branding
- Keyboard shortcut reminder
## Color Scheme
**Background:**
- Dark: `#1e1e1e` (VS Code inspired)
- Cards: `#2d2d2d`
- Borders: `#3e3e3e`
**Text:**
- Primary: `#d4d4d4`
- Accent: `#4ec9b0` (teal/green)
- Muted: `#858585`
**Graph Nodes:**
- Exactly as in the generated SVG
- Matches console output colors
## Workflow
```
┌──────────────────────────────────────────────────────────┐
│ 1. You're viewing a page │
│ (e.g., example.com) │
└──────────────────────────────────────────────────────────┘
↓
Press Ctrl+Shift+D
↓
┌──────────────────────────────────────────────────────────┐
│ 2. Console Output (Terminal) │
│ ═══════════════════════════════ │
│ DOM TREE STRUCTURE: │
│ <html> │
│ <body> │
│ <h1> │
│ Text: 'Example' │
└──────────────────────────────────────────────────────────┘
↓
(simultaneously)
↓
┌──────────────────────────────────────────────────────────┐
│ 3. New Tab Opens │
│ about:dom-graph?path=/home/.../.cache/...svg │
│ │
│ Shows beautiful visualization with: │
│ • Color legend │
│ • Interactive graph │
│ • Dark theme │
└──────────────────────────────────────────────────────────┘
↓
Keep working!
↓
┌──────────────────────────────────────────────────────────┐
│ 4. Continue browsing │
│ • Graph tab stays open │
│ • Switch back anytime │
│ • Generate new graphs anytime │
└──────────────────────────────────────────────────────────┘
```
## Comparison
### Before (External Viewer)
```
Browser → Ctrl+Shift+D → xdg-open → SVG Viewer
↓ ↑
└──────── Switch apps ────────────────┘
```
### After (Browser Tab)
```
Browser → Ctrl+Shift+D → New Tab → View Graph
└────────── All in Bowser ────────────┘
```
## Advantages
1. **No App Switching** - Everything in browser
2. **Consistent UX** - Same interface as other pages
3. **Always Available** - No need for external apps
4. **Better Integration** - Part of your browsing session
5. **More Features** - Legend, hints, instructions
6. **Beautiful Design** - Custom dark theme
7. **Responsive** - Works at any size
## Next Steps
Try it yourself:
1. Open Bowser
2. Navigate to any page (or use the test page)
3. Press **Ctrl+Shift+D**
4. Enjoy the beautiful DOM visualization!

97
docs/DOM_VISUALIZATION.md
View file

@ -1,97 +0,0 @@
# DOM Visualization Feature
## Overview
The DOM visualization feature allows you to inspect the Document Object Model (DOM) tree of the currently loaded page as a graph. This is useful for debugging, understanding page structure, and learning how browsers parse HTML.
## Usage
### Keyboard Shortcut
Press **Ctrl+Shift+D** while viewing any page to generate a DOM graph.
### What Happens
1. **Console Output**: The DOM tree structure is printed to the console in text format
2. **Graph File**: A graph file is generated in `~/.cache/bowser/`
3. **New Browser Tab**: Opens automatically displaying the visualization
- Shows interactive SVG graph (if Graphviz installed)
- Shows DOT format with installation instructions (if Graphviz not installed)
### Graph Features
- **Color-Coded Nodes**: Different element types have different colors
- Light green: `<html>`, `<body>`
- Light yellow: Headings (`<h1>`, `<h2>`, etc.)
- Light gray: Block elements (`<div>`, `<p>`, `<span>`)
- Light cyan: Lists (`<ul>`, `<ol>`, `<li>`)
- Light pink: Interactive elements (`<a>`, `<button>`)
- White: Other elements
- **Node Labels**: Show element tags and up to 3 attributes
- **Text Nodes**: Display text content (truncated to 50 characters)
- **Hierarchical Layout**: Shows parent-child relationships with arrows
## Installation (Optional)
For visual graph rendering, install Graphviz:
```bash
# Debian/Ubuntu
sudo apt install graphviz
# macOS
brew install graphviz
# Fedora
sudo dnf install graphviz
```
Without Graphviz, the tool will save a `.dot` file that you can:
- Open with a text editor to see the graph definition
- Render online at http://www.webgraphviz.com/
- Render with `dot -Tsvg dom_graph.dot -o dom_graph.svg`
## Output Files
All generated files are saved to `~/.cache/bowser/`:
- `dom_graph.svg` - Visual graph (if Graphviz available)
- `dom_graph.dot` - Graph definition in DOT format
## Examples
### Simple Page
```html
<html>
<body>
<h1>Title</h1>
<p>Content</p>
</body>
</html>
```
Will generate a graph showing:
```
html (green) → body (green) → h1 (yellow) → "Title" (blue text node)
→ p (gray) → "Content" (blue text node)
```
### Testing
A test page is included at `test_dom.html`. Open it with:
```bash
uv run bowser file://$(pwd)/test_dom.html
```
Then press Ctrl+Shift+D to visualize its DOM structure.
## Implementation
The visualization is implemented in:
- `src/debug/dom_graph.py` - Graph generation logic
- `src/browser/chrome.py` - Keyboard shortcut handler
The feature uses:
- **Graphviz DOT format** for graph definition
- **Recursive tree traversal** to build node hierarchy
- **GTK keyboard event handling** for the shortcut

16
src/parser/html.py
View file

@ -27,12 +27,12 @@ class Element:
def __repr__(self): # pragma: no cover - debug helper
return f"Element({self.tag!r}, {self.attributes!r})"
@property
def bounding_box(self):
"""Get bounding box from layout if available."""
if self.layout:
return (self.layout.x, self.layout.y,
return (self.layout.x, self.layout.y,
self.layout.x + self.layout.width,
self.layout.y + self.layout.height)
return None
@ -99,7 +99,7 @@ class _DOMBuilder(HTMLParser):
return
if self._skip_depth > 0:
return
# Skip html/head tags - we handle structure ourselves
if tag == "html":
return # Use our root instead
@ -114,14 +114,14 @@ class _DOMBuilder(HTMLParser):
self.root.children.append(self._body)
self.current = self._body
return
attr_dict = {k: v for k, v in attrs}
el = Element(tag, attr_dict)
# Ensure we're inside a body
if self.current is self.root:
self._ensure_body()
self._push(el)
def handle_endtag(self, tag):
@ -145,11 +145,11 @@ class _DOMBuilder(HTMLParser):
text = re.sub(r"\s+", " ", text)
if not text.strip():
return # Skip whitespace-only text at root level
# Ensure we're inside a body for text content
if self.current is self.root:
self._ensure_body()
self._append_text(text)
def handle_entityref(self, name):

35
test_dom.html
View file

@ -1,35 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>DOM Test Page</title>
</head>
<body>
<h1>DOM Visualization Test</h1>
<p>This page demonstrates the DOM visualization feature.</p>
<div class="container">
<h2>Section 1</h2>
<p>Press <strong>Ctrl+Shift+D</strong> to visualize the DOM tree.</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</div>
<div class="features">
<h2>Features</h2>
<ol>
<li>Color-coded nodes by element type</li>
<li>Visual hierarchy representation</li>
<li>Text content preview</li>
</ol>
</div>
<footer>
<p>Bowser Browser - Educational Project</p>
</footer>
</body>
</html>