# HTML Viewer — Obsidian Community Plugin

Render `.html` files directly inside Obsidian. Sandboxed by default — toggle **Scripts ON** for games, D3/ECharts visualizations, and interactive documents.

---

## Installation

### Manual (from this repo)

Copy the `html-viewer/` folder into `<vault>/.obsidian/plugins/`, then enable it in Settings → Community Plugins.

```
.obsidian/plugins/html-viewer/
├── manifest.json
├── main.js
├── styles.css
└── README.md
```

Restart Obsidian or reload plugins (Ctrl+P → "Reload plugins").

---

## Usage

1. Place any `.html` or `.htm` file in your vault
2. Click it in the file explorer → opens in HTML Viewer
3. Use the toolbar:

| Button | Function |
|--------|----------|
| **Source / Rendered** | Toggle between raw HTML source and rendered view |
| **Scripts: OFF / ON** | Enable/disable JavaScript execution (default: OFF) |
| **Refresh** | Reload the file from disk |

Or via command palette: **Open HTML viewer**.

---

## Modes

### Safe Mode (Scripts OFF — default)

- All `<script>` tags removed
- Inline event handlers (`onclick`, `onerror`, etc.) stripped
- `javascript:` pseudo-URLs neutralized
- iframe sandbox: `allow-same-origin`

Use for: static pages, untrusted HTML, document previews.

### Interactive Mode (Scripts ON)

- JavaScript execution enabled
- Event handlers and `javascript:` links still stripped
- Auto-focus injected so keyboard games work immediately
- iframe sandbox: `allow-scripts allow-same-origin`

Use for: Canvas games, D3.js / ECharts / Three.js visualizations, interactive tutorials, and any **trusted** local HTML with scripts.

---

## Supported Features

| Feature | Safe Mode | Interactive Mode |
|---------|:---------:|:----------------:|
| HTML + CSS | ✅ | ✅ |
| Images, video, audio | ✅ | ✅ |
| External CSS/images (CDN) | ✅ | ✅ |
| Anchor links (`#section`) | ✅ | ✅ |
| `<canvas>` 2D / WebGL | — | ✅ |
| JavaScript applications | — | ✅ |
| External `<script src="...">` | — | ✅ |
| Keyboard input (games) | — | ✅ |
| `localStorage` | — | ⚠️ session-only* |
| File auto-refresh (external edit) | ✅ | ✅ |

\* `localStorage` works within a session but resets on refresh because each render uses a new Blob URL.

## Blocked by Design

These are intentionally unavailable for security, even in Interactive Mode:

- Form submission (no `allow-forms`)
- Popup windows (no `allow-popups`)
- File upload (`<input type="file">`)
- Top-level navigation (no `allow-top-navigation`)
- Access to `window.parent` / Obsidian DOM
- Inline event handlers — always stripped
- `javascript:` URLs — always neutralized

---

## Smart Features

- **Dedup**: clicking the same HTML file twice focuses the existing tab instead of opening a duplicate
- **Auto-refresh**: edits to the HTML file in an external editor are picked up automatically
- **Delete handling**: if the HTML file is deleted, the view shows a clear message
- **Race-condition guard**: rapid file switching won't cause stale renders
- **Blob URL cleanup**: memory properly released when closing tabs or switching files

---

## Compatibility

- **Desktop**: Windows, macOS, Linux — full support
- **Mobile**: iOS / Android — supported (`isDesktopOnly: false`). Keyboard auto-focus is desktop-only; tap the game area for touch controls
- **Obsidian ≥ 1.0.0**
- **Themes**: uses Obsidian CSS variables — adapts to any theme

---

## Security Model

```
┌──────────────────────────────────────────┐
│            Obsidian Window               │
│  ┌────────────────────────────────────┐  │
│  │  Toolbar: [Source] [Scripts] [↻]   │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │  Sandboxed iframe                  │  │
│  │  ┌──────────────────────────────┐  │  │
│  │  │  Stripped: <script>,         │  │  │
│  │  │  on*=, javascript:           │  │  │
│  │  │  Blocked: forms, popups,     │  │  │
│  │  │  file access, navigation     │  │  │
│  │  └──────────────────────────────┘  │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘
```

Double-layer protection: regex sanitization at the content level + browser sandbox at the iframe level.

---

## Version History

| Version | Changes |
|---------|---------|
| 1.2.0 | CSS namespace prefix (`html-viewer-`); race-condition guard; auto-refresh on external edit; delete handling; mobile-ready manifest |
| 1.1.2 | Strip `javascript:` pseudo-URLs |
| 1.1.1 | Auto-focus iframe for keyboard games |
| 1.1.0 | Scripts ON/OFF toggle |
| 1.0.2 | Dedup: same file → focus existing tab |
| 1.0.1 | Blob URL instead of srcdoc (fixes anchor navigation); flex layout |
| 1.0.0 | Initial release |

---

## License

MIT