# HTML Slide Studio

HTML Slide Studio is a Markdown-first presentation workspace built with React, Marp, and CodeMirror. It combines live slide preview, browser presentation mode, Mermaid diagrams, reusable style presets, offline HTML export, and a local MCP server for agent authoring.

## Features

- Edit Marp Markdown with a live 16:9 preview
- Navigate with thumbnails, keyboard controls, or fullscreen presentation mode
- Render editable Mermaid fences and export them as embedded SVG data
- Choose from seven style presets or add deck-specific CSS
- Apply the optional Narrative Infographic design profile and diagnostics
- Open and save `deck.md + assets/` folders through the browser
- Export a self-contained HTML presentation with a restrictive offline CSP
- Create, validate, and export decks through a constrained stdio MCP server

## Quick Start

Requirements:

- Node.js 22 or newer
- npm
- Microsoft Edge or another Chromium browser for local authoring

```bash
npm ci
npm run dev
```

Open the URL printed by Vite, normally `http://127.0.0.1:5173/`.

The repository includes one generic `example-deck`. User-created decks are ignored by Git by default so presentation content is not accidentally published.

## Authoring Decks

The canonical structure is:

```text
decks/<deck-id>/
├── deck.md
└── assets/
    ├── diagram.svg
    └── screenshot.png
```

Use **Open folder** to grant read/write access to an existing deck folder. Markdown changes update the preview immediately. Use the save icon or `Ctrl+S` to write back to `deck.md`.

Bundled decks opened with `?deck=<deck-id>` can be saved only while the local Vite development or preview server is running. The save endpoint accepts existing deck IDs only and is not included in production builds.

To intentionally version additional decks, update the deck rules in `.gitignore` first.

## Mermaid

Add an editable Mermaid fence:

````markdown
```mermaid
flowchart LR
  Source --> Preview --> Export
```
````

The editor renders it in the browser. Offline export replaces the fence with Base64-encoded SVG image data; Mermaid source and runtime code are not included in the exported HTML.

## MCP Server

The included VS Code configuration starts the MCP server with:

```bash
npm run mcp
```

For another MCP client, configure a stdio server with command `npm`, arguments `run mcp`, and this repository as the working directory.

Available tools:

- `htmlslide_list_decks`
- `htmlslide_get_deck`
- `htmlslide_create_deck`
- `htmlslide_update_deck`
- `htmlslide_put_asset`
- `htmlslide_validate_deck`
- `htmlslide_export_html`

The MCP server confines access to the configured deck root, rejects path traversal and symlink escapes, validates passive assets, and blocks remote dependencies during offline export.

## Scripts

| Command | Purpose |
| --- | --- |
| `npm run dev` | Start the Vite development server |
| `npm run build` | Type-check and build the application |
| `npm test` | Run unit and MCP tests |
| `npm run test:e2e` | Build and run Playwright browser tests |
| `npm run lint` | Run oxlint |
| `npm run typecheck` | Type-check app and Vite configuration |
| `npm run typecheck:mcp` | Type-check the MCP server |
| `npm run mcp` | Start the stdio MCP server |
| `npm run mcp:inspect` | Open the MCP Inspector |

## Architecture

- `src/App.tsx` — editor, preview, presentation, save, and export workflows
- `src/render/` — Marp rendering and slide source ranges
- `src/mermaid/` — secure Mermaid expansion and SVG validation
- `src/export/` — offline single-file HTML generation
- `src/design/` — design profiles, diagnostics, and shared themes
- `mcp/` — constrained deck repository and MCP server
- `design-profiles/` — reusable authoring guidance
- `decks/example-deck/` — public, non-customer example

## Security and Privacy

- Keep confidential decks outside this repository or rely on the default ignored `decks/*` paths.
- Do not expose the Vite development server to an untrusted network when local deck saving is enabled.
- Export requires local assets and rejects external runtime dependencies.
- See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## License

MIT. See [LICENSE](LICENSE).