mockshot 1.0.1

Generate pixel-perfect fake screenshots of VS Code, Chrome, Safari, Terminal and hand-drawn diagrams (Merise + UML)

MockShot

Generate pixel-perfect fake screenshots of VS Code, Chrome, Safari, Terminal, and hand-drawn diagrams (Merise + UML) for university reports, documentation, and presentations.

No real apps needed. Just JSON + one command = screenshot.

Screenshots

VS Code	Chrome Light	Safari Light

Chrome Dark	Safari Dark

Linux Terminal	macOS Terminal	Windows Terminal

Diagrams (Hand-drawn)

Gantt	MCD (Merise)	UML Class

MCC	MCT	MLD

Use Case	Sequence	Activity

State Machine	Component	Deployment

Requirements

Dependency	Windows	macOS	Linux
Python	3.9+	3.9+	3.9+
Playwright	Auto via pip install	Auto via pip install	Auto via pip install
Browser	Edge (pré-installé)	Chrome (télécharger)	Chromium (sudo apt install chromium-browser)

Si aucun navigateur Chromium-based n'est détecté, MockShot affiche les instructions d'installation adaptées à votre OS.

Installation

git clone https://github.com/your-username/mockshot.git
cd mockshot
pip install -e .

MockShot détecte automatiquement le navigateur disponible sur votre machine :

OS	Navigateur utilisé	Action requise
Windows	Edge (pré-installé)	Aucune
macOS	Chrome (si installé)	Installer Chrome ou playwright install chromium
Linux	Chrome/Chromium (si installé)	sudo apt install chromium-browser ou playwright install chromium

Plus besoin de playwright install chromium si un navigateur Chromium-based est déjà installé.

Quick Start

# Instant screenshot of a single file
mockshot quick app.py

# Scan a real project → JSON → screenshot
mockshot scan ./myproject --active src/main.py -o project.json
mockshot vscode --project project.json -o screenshot.png

---

How It Works

Each screenshot type has its own characteristics — they are fully separated:

Type	Theme	Content	Output
VS Code (vscode, quick, scan)	Always Dark+ — no theme option	Any source code file	PNG
Terminal (terminal)	Determined by OS — no theme option	Commands + output via JSON	PNG
Browser (browser)	Light or Dark — user choice	Web-interpretable files only	PNG
Diagrams (gantt, merise, uml)	Hand-drawn (Excalidraw style)	JSON structure	SVG, PNG, PDF

11 diagram types: Gantt · Merise MCD, MCC, MCT, MLD · UML Class, Use Case, Sequence, Activity, State, Component, Deployment

Browser content restriction: Only files that a browser can actually interpret are accepted. Passing a .py, .rs, or other code file will return an error — use mockshot vscode or mockshot quick for those.

--project accepts both file paths and inline JSON

All commands that support --project auto-detect the input:

# From a file
mockshot vscode --project project.json -o screenshot.png

# Inline JSON — same result, no file needed
mockshot vscode --project '{"root":"myapp","tree":[{"name":"src","open":true,"children":[{"name":"app.py"}]}]}' -o screenshot.png

This makes MockShot fully usable by LLMs and scripts — no intermediate files required.

--format controls stdout output

All screenshot commands support --format:

Value	Output	For
file	✓ Saved screenshot.png	Humans (default)
path	/absolute/path/to/screenshot.png	Scripts — easy to parse
base64	Raw base64-encoded PNG	LLMs — no file reading needed

# Human-friendly (default)
mockshot quick app.py
# ✓ Saved screenshot.png

# Script-friendly
mockshot quick app.py --format path
# /home/user/project/screenshot.png

# LLM-friendly — image data directly in stdout
mockshot quick app.py --format base64
# iVBORw0KGgoAAAANSUhEUgAAB4AAAAQ4CAIAA...

---

VS Code Commands

VS Code screenshots are always rendered in Dark+ theme. There is no theme option.

mockshot quick — Instant file screenshot

One file, one command. No tree, no tabs, no JSON.

mockshot quick <file> [options]

Option	Default	Description
--visible	—	Line range to show, e.g. 25-70
--width	1920	Image width
--height	1080	Image height
-o	screenshot.png	Output path
--format	file	file, path, or base64

mockshot quick app.py
mockshot quick src/main.rs --visible 10-50 -o main.png

mockshot scan — Auto-generate project JSON

Scans a real directory and outputs the JSON needed for mockshot vscode.

mockshot scan <directory> [options]

Option	Default	Description
--active	—	Relative path to the active file
--branch	main	Git branch name
--visible	—	Line range, e.g. 25-70
--depth	4	Max scan depth
-o	project.json	Output path

mockshot scan ./myproject --active src/app.py --branch feature/api -o project.json

Auto-skips: __pycache__, .git, node_modules, .venv, dist, build, binaries.

mockshot vscode — Full VS Code screenshot

Sidebar, tabs, breadcrumbs, minimap, status bar — the full IDE.

mockshot vscode --project <json_file_or_inline> [options]

Project JSON format:

{
  "root": "myproject",
  "tabs": ["app.py", "config.py"],
  "active_file": {
    "name": "app.py",
    "language": "python",
    "content_path": "src/app.py",
    "visible_lines": [25, 70]
  },
  "git_branch": "main",
  "tree": [
    { "name": "src", "open": true, "children": [
      { "name": "app.py" },
      { "name": "config.py" }
    ]},
    { "name": "tests", "open": false, "children": [] },
    { "name": "README.md" }
  ]
}

Option	Default	Description
--project	—	JSON file path or inline JSON string
--file	—	Override: source code file
--code	—	Override: inline code string
--lang	python	Override: language
--filename	—	Override: tab filename
--tabs	—	Override: comma-separated tabs
--git-branch	main	Override: git branch
--width	1920	Image width
--height	1080	Image height
-o	screenshot.png	Output path
--format	file	file, path, or base64

# From file
mockshot vscode --project project.json -o vscode.png

# Inline JSON
mockshot vscode --project '{"root":"app","tree":[{"name":"main.py"}]}' -o vscode.png

# Simple overrides
mockshot vscode --file app.py --lang python -o vscode.png
mockshot vscode --code "print('hello')" --lang python -o vscode.png

---

Terminal Command

Terminal appearance is determined by the OS — there is no theme option. Each OS has its own look: GNOME (Linux), Terminal.app (macOS), Windows Terminal (Windows).

mockshot terminal

mockshot terminal --project <json_file_or_inline> [options]

Project JSON format:

{
  "os": "linux",
  "user": "andil",
  "host": "mc-desktop",
  "cwd": "~/projects/myapp",
  "commands": [
    {
      "cmd": "python -m pytest tests/ -v",
      "output": [
        "tests/test_api.py::test_health PASSED",
        "====== 1 passed in 0.42s ======"
      ]
    },
    {
      "cmd": "docker compose up -d",
      "output": ["Container myapp-api-1  Started"]
    }
  ]
}

Option	Default	Description
--project	—	JSON file path or inline JSON string
--os	linux	Override: linux, macos, windows
--user	user	Override: username
--host	desktop	Override: hostname
--cwd	~	Override: working directory
--commands	—	Legacy: text file with $ command
--inline	—	Inline commands text
--width	1920	Image width
--height	1080	Image height
-o	screenshot.png	Output path
--format	file	file, path, or base64

# From file
mockshot terminal --project terminal.json -o terminal.png

# Inline JSON
mockshot terminal --project '{"os":"linux","user":"andil","host":"mc","cwd":"~/app","commands":[{"cmd":"make build","output":["OK"]}]}' -o terminal.png

---

Browser Command

Browser screenshots support Chrome and Safari, each with light and dark themes. This is the only screenshot type with a theme option.

Content must be browser-interpretable: .html, .json, .xml, .svg, .txt, .csv, .log, .css, .js. For code files (.py, .rs, etc.), use mockshot vscode or mockshot quick instead — passing non-web files will return an error.

mockshot browser

mockshot browser --project <json_file_or_inline> [options]

Project JSON format:

{
  "browser": "chrome",
  "theme": "light",
  "url": "https://api.example.com/data",
  "title": "API Response",
  "content_path": "response.json"
}

Option	Default	Description
--project	—	JSON file path or inline JSON string
--url	https://example.com	URL in address bar
--content	—	Content file (.json, .html, .xml...)
--text	—	Inline content text
--browser	chrome	chrome or safari
--title	—	Page title in tab
--theme	light	light or dark
--width	1920	Image width
--height	1080	Image height
-o	screenshot.png	Output path
--format	file	file, path, or base64

# Chrome light (default)
mockshot browser --url https://api.example.com/health --content response.json

# Safari dark
mockshot browser --url https://reddit.com --browser safari --theme dark -o safari.png

# From JSON file
mockshot browser --project browser.json -o browser.png

# Inline JSON
mockshot browser --project '{"browser":"safari","theme":"dark","url":"https://example.com","title":"Test"}' -o safari.png

# Inline content text
mockshot browser --text '{"status":"ok","data":[1,2,3]}' --url https://api.example.com -o api.png

---

Diagrams (Hand-drawn, Excalidraw style)

All diagrams are rendered in a hand-drawn style using the Virgil font (from Excalidraw) — black pen strokes on white background, like a whiteboard sketch.

Output format is auto-detected from the -o extension:

• .svg — native SVG (no browser needed)
• .png — rendered via Playwright
• .pdf — rendered via Playwright

mockshot gantt — Gantt Chart

mockshot gantt --project <json_file_or_inline> [options]

Project JSON format:

{
  "title": "Sprint 1",
  "tasks": [
    {"name": "Analyse", "start": "2024-03-01", "end": "2024-03-05", "group": "Phase 1"},
    {"name": "Dev API", "start": "2024-03-04", "end": "2024-03-12", "group": "Phase 2"},
    {"name": "Tests", "start": "2024-03-10", "end": "2024-03-15", "group": "Phase 2", "progress": 60}
  ]
}

Option	Default	Description
--project	—	JSON file path or inline JSON string
--seed	42	Random seed (same seed = same sketch)
-o	gantt.svg	Output path (.svg, .png, .pdf)
--format	file	file, path, or base64

mockshot gantt --project gantt.json -o gantt.svg
mockshot gantt --project '{"title":"Sprint","tasks":[{"name":"Dev","start":"2024-01-01","end":"2024-01-10"}]}' -o gantt.png

Merise Diagrams

All Merise diagrams share the same options:

Option	Default	Description
--project	—	JSON file path or inline JSON string
--seed	42	Random seed (same seed = same sketch)
-o	<type>.svg	Output path (.svg, .png, .pdf)
--format	file	file, path, or base64

mockshot merise mcd — Modèle Conceptuel de Données

{
  "entities": [
    {"name": "ETUDIANT", "attrs": ["id_etudiant", "nom", "prenom"], "pk": "id_etudiant"},
    {"name": "COURS", "attrs": ["id_cours", "intitule", "credits"], "pk": "id_cours"}
  ],
  "associations": [
    {
      "name": "INSCRIT",
      "from": "ETUDIANT", "to": "COURS",
      "card_from": "0,N", "card_to": "1,N",
      "attrs": ["date_inscription"]
    }
  ]
}

mockshot merise mcd --project mcd.json -o mcd.svg

mockshot merise mcc — Modèle Conceptuel de Communication

{
  "actors": [{"name": "Client"}, {"name": "Banque"}],
  "domains": [{"name": "Gestion Commandes"}],
  "flows": [
    {"from": "Client", "to": "Gestion Commandes", "label": "Commande"},
    {"from": "Gestion Commandes", "to": "Banque", "label": "Paiement"}
  ]
}

domains is optional — set to null or omit to render actors only.

mockshot merise mcc --project mcc.json -o mcc.svg

mockshot merise mct — Modèle Conceptuel de Traitements

{
  "processes": [
    {"name": "Vérifier stock", "type": "process"},
    {"name": "Commande reçue", "type": "event"},
    {"name": "Stock OK", "type": "result"}
  ],
  "flows": [
    {"from": "Commande reçue", "to": "Vérifier stock"},
    {"from": "Vérifier stock", "to": "Stock OK"}
  ]
}

mockshot merise mct --project mct.json -o mct.svg

mockshot merise mld — Modèle Logique de Données

{
  "tables": [
    {
      "name": "ETUDIANT",
      "columns": ["id_etudiant PK", "nom", "prenom"],
      "pk": "id_etudiant"
    },
    {
      "name": "COURS",
      "columns": ["id_cours PK", "intitule"],
      "pk": "id_cours"
    }
  ],
  "relations": [
    {"from": "ETUDIANT", "to": "COURS", "type": "1:N", "label": "inscrit"}
  ]
}

mockshot merise mld --project mld.json -o mld.svg

UML Diagrams

All UML diagrams share the same options:

Option	Default	Description
--project	—	JSON file path or inline JSON string
--seed	42	Random seed (same seed = same sketch)
-o	<type>.svg	Output path (.svg, .png, .pdf)
--format	file	file, path, or base64

mockshot uml class — Class Diagram

{
  "classes": [
    {
      "name": "User",
      "stereotype": "entity",
      "attrs": ["-id: int", "-name: str", "+email: str"],
      "methods": ["+login(): bool", "+logout(): void"]
    },
    {
      "name": "Post",
      "attrs": ["-id: int", "-title: str"],
      "methods": ["+publish(): void"]
    }
  ],
  "relations": [
    {"from": "User", "to": "Post", "type": "composition", "label": "writes", "from_card": "1", "to_card": "0..*"}
  ]
}

Relation types: association, aggregation, composition, inheritance, implementation, dependency

mockshot uml class --project class.json -o class.svg

mockshot uml usecase — Use Case Diagram

{
  "system": "Application Web",
  "actors": [{"name": "Client"}, {"name": "Admin"}],
  "usecases": [{"name": "Se connecter"}, {"name": "Gérer utilisateurs"}],
  "relations": [
    {"from": "Client", "to": "Se connecter", "type": "association"},
    {"from": "Se connecter", "to": "Vérifier identité", "type": "include"},
    {"from": "Gérer utilisateurs", "to": "Se connecter", "type": "extend"}
  ]
}

Relation types: association (solid line), include (dashed + «include»), extend (dashed + «extend»), generalization (triangle head)

mockshot uml usecase --project usecase.json -o usecase.svg

mockshot uml sequence — Sequence Diagram

{
  "participants": ["Client", "Serveur", "BDD"],
  "messages": [
    {"from": "Client", "to": "Serveur", "label": "requête HTTP"},
    {"from": "Serveur", "to": "BDD", "label": "SELECT *"},
    {"from": "BDD", "to": "Serveur", "label": "résultats", "type": "reply"},
    {"from": "Serveur", "to": "Client", "label": "réponse JSON", "type": "reply"}
  ]
}

Message types: call (default, solid arrow), reply (dashed arrow)

mockshot uml sequence --project sequence.json -o sequence.svg

mockshot uml activity — Activity Diagram

{
  "nodes": [
    {"name": "Start", "type": "start"},
    {"name": "Vérifier stock", "type": "action"},
    {"name": "En stock ?", "type": "decision"},
    {"name": "Expédier", "type": "action"},
    {"name": "Commander fournisseur", "type": "action"},
    {"name": "End", "type": "end"}
  ],
  "edges": [
    {"from": "Start", "to": "Vérifier stock"},
    {"from": "Vérifier stock", "to": "En stock ?"},
    {"from": "En stock ?", "to": "Expédier", "label": "oui"},
    {"from": "En stock ?", "to": "Commander fournisseur", "label": "non"},
    {"from": "Expédier", "to": "End"},
    {"from": "Commander fournisseur", "to": "End"}
  ]
}

Node types: start, end, action, decision, fork, join

mockshot uml activity --project activity.json -o activity.svg

mockshot uml state — State Machine Diagram

{
  "states": [
    {"name": "Idle", "type": "state"},
    {"name": "Processing", "type": "state"},
    {"name": "Start", "type": "start"},
    {"name": "End", "type": "end"}
  ],
  "transitions": [
    {"from": "Start", "to": "Idle"},
    {"from": "Idle", "to": "Processing", "label": "submit()"},
    {"from": "Processing", "to": "Idle", "label": "done"},
    {"from": "Processing", "to": "End", "label": "error"}
  ]
}

mockshot uml state --project state.json -o state.svg

mockshot uml component — Component Diagram

{
  "components": [
    {"name": "WebApp", "stereotype": "frontend"},
    {"name": "API", "stereotype": "backend"},
    {"name": "Database"}
  ],
  "relations": [
    {"from": "WebApp", "to": "API", "label": "REST", "type": "dependency"},
    {"from": "API", "to": "Database", "type": "dependency"}
  ]
}

mockshot uml component --project component.json -o component.svg

mockshot uml deployment — Deployment Diagram

{
  "nodes": [
    {"name": "Web Server", "stereotype": "device"},
    {"name": "App Server", "stereotype": "execution environment"},
    {"name": "DB Server"}
  ],
  "relations": [
    {"from": "Web Server", "to": "App Server", "label": "HTTP"},
    {"from": "App Server", "to": "DB Server", "label": "TCP/IP"}
  ]
}

mockshot uml deployment --project deployment.json -o deployment.svg

---

LLM Usage

MockShot is designed to be fully usable by LLMs without creating intermediate files:

# Screenshot any existing file — one command
mockshot quick src/app.py -o screenshot.png --format path

# Generate code inline and screenshot it
mockshot vscode --code "def hello():\n    return 'world'" --lang python --filename app.py --format base64

# Terminal with inline JSON — get base64 directly
mockshot terminal --project '{"os":"linux","user":"dev","host":"server","cwd":"~/app","commands":[{"cmd":"python manage.py migrate","output":["Operations to perform:","  Apply all migrations: auth, contenttypes","Running migrations:","  Applying auth.0001_initial... OK"]}]}' --format base64

# Browser with inline content
mockshot browser --text '<h1>Hello World</h1><p>Welcome</p>' --url https://mysite.com --title "My Site" --format path

# Hand-drawn Gantt chart
mockshot gantt --project '{"title":"Sprint","tasks":[{"name":"Dev","start":"2024-01-01","end":"2024-01-10"}]}' -o gantt.svg

# Hand-drawn MCD
mockshot merise mcd --project '{"entities":[{"name":"USER","attrs":["id","name"],"pk":"id"}],"associations":[]}' --format base64

# Hand-drawn MCC
mockshot merise mcc --project '{"actors":[{"name":"Client"},{"name":"Serveur"}],"flows":[{"from":"Client","to":"Serveur","label":"Requête"}]}' -o mcc.svg

# Hand-drawn UML class diagram
mockshot uml class --project '{"classes":[{"name":"User","attrs":["-id: int"],"methods":["+login(): bool"]}],"relations":[]}' -o class.png --format path

# UML use case
mockshot uml usecase --project '{"system":"App","actors":[{"name":"User"}],"usecases":[{"name":"Login"}],"relations":[{"from":"User","to":"Login","type":"association"}]}' -o usecase.svg

# UML sequence
mockshot uml sequence --project '{"participants":["Client","Server"],"messages":[{"from":"Client","to":"Server","label":"request"}]}' -o sequence.svg

---

Supported Icons

File icons (auto-detected from extension): Python, JavaScript, TypeScript, HTML, CSS, JSON, Markdown, YAML, TOML, XML, Java, C, C++, Rust, Go, Bash, SQL, Docker, Git, and more.

Folder icons (auto-detected from name): src, lib, dist, build, node_modules, test, docs, config, api, app, assets, components, styles, database, server, client, and 50+ more.

---

Project Structure

mockshot/
├── mockshot/
│   ├── cli.py              # CLI commands (click)
│   ├── core.py              # ScreenshotConfig
│   ├── renderer.py          # HTML/SVG → PNG/PDF (Playwright)
│   ├── scanner.py           # Directory scanner for `scan`
│   ├── asset_loader.py      # Fonts & icons (base64)
│   ├── templates/
│   │   ├── vscode.py        # VS Code logic (always Dark+)
│   │   ├── terminal.py      # Terminal logic (OS-dependent)
│   │   └── browser.py       # Browser logic (light/dark theme)
│   ├── diagrams/
│   │   ├── sketch.py        # Hand-drawn SVG primitives (Excalidraw style)
│   │   ├── layout.py        # Graph layout (Graphviz dot/neato)
│   │   ├── routing.py       # Shared edge routing (angle-based geometric)
│   │   ├── gantt.py         # Gantt chart
│   │   ├── merise_mcd.py    # Merise MCD
│   │   ├── merise_mcc.py    # Merise MCC
│   │   ├── merise_mct.py    # Merise MCT
│   │   ├── merise_mld.py    # Merise MLD
│   │   ├── uml_class.py     # UML Class diagram
│   │   ├── uml_usecase.py   # UML Use Case diagram
│   │   ├── uml_sequence.py  # UML Sequence diagram
│   │   ├── uml_activity.py  # UML Activity diagram
│   │   ├── uml_state.py     # UML State Machine diagram
│   │   ├── uml_component.py # UML Component diagram
│   │   └── uml_deployment.py # UML Deployment diagram
│   ├── html_templates/
│   │   ├── vscode.html      # VS Code Dark+ template
│   │   ├── chrome.html      # Chrome light/dark template
│   │   ├── safari.html      # Safari light/dark template
│   │   └── terminal.html    # Terminal (Linux/macOS/Windows)
│   └── assets/
│       ├── fonts/            # JetBrains Mono, Virgil (hand-drawn)
│       ├── icons/            # Material Icon Theme SVGs
│       └── codicon.ttf       # VS Code codicon font
├── examples/
│   ├── diagrams/
│   │   ├── json/            # Example JSON for all diagram types
│   │   ├── *.svg            # Generated SVG diagrams
│   │   ├── *.png            # Generated PNG diagrams
│   │   └── *.pdf            # Generated PDF diagrams
│   └── *.json / *.png       # Example JSON + screenshots
└── pyproject.toml

Contributing

Setup

git clone https://github.com/your-username/mockshot.git
cd mockshot
python -m venv .venv
source .venv/bin/activate
pip install -e .

Architecture

HTML/CSS + Playwright pipeline:

1. Python (templates/*.py) builds template data
2. Jinja2 (html_templates/*.html) renders pixel-perfect HTML/CSS
3. Playwright (renderer.py) captures it as PNG

All fonts and icons are base64-encoded inline — zero external deps at render time.

Design rules

Each screenshot type is fully separated with its own characteristics:

• VS Code — always Dark+ theme, no theme parameter in code
• Terminal — the OS (linux, macos, windows) determines the look, no theme parameter
• Browser — the only type with a theme parameter (light/dark), and only accepts web-interpretable content

Adding a new template

1. Create mockshot/html_templates/mytemplate.html
2. Create mockshot/templates/mytemplate.py with a render() function
3. Add a CLI command in mockshot/cli.py

Adding icons

1. Add SVG to mockshot/assets/icons/
2. For folders: add folder-name.svg + folder-name-open.svg
3. Register in mockshot/asset_loader.py (EXT_TO_ICON, FILENAME_TO_ICON, or FOLDER_TO_ICON)

Testing

mockshot quick mockshot/cli.py -o /tmp/test.png
mockshot vscode --project examples/tree.json -o /tmp/test.png
mockshot terminal --project examples/terminal.json -o /tmp/test.png
mockshot browser --project examples/browser.json -o /tmp/test.png
mockshot gantt --project '{"title":"Test","tasks":[{"name":"Task","start":"2024-01-01","end":"2024-01-05"}]}' -o /tmp/test.svg
mockshot merise mcd --project '{"entities":[{"name":"USER","attrs":["id"],"pk":"id"}],"associations":[]}' -o /tmp/test.svg
mockshot merise mcc --project '{"actors":[{"name":"A"}],"flows":[]}' -o /tmp/test.svg
mockshot merise mct --project examples/diagrams/json/mct_mega.json -o /tmp/test.svg
mockshot merise mld --project examples/diagrams/json/mld_mega.json -o /tmp/test.svg
mockshot uml class --project '{"classes":[{"name":"User","attrs":["-id: int"],"methods":[]}],"relations":[]}' -o /tmp/test.svg
mockshot uml usecase --project examples/diagrams/json/usecase_mega.json -o /tmp/test.svg
mockshot uml sequence --project examples/diagrams/json/sequence_mega.json -o /tmp/test.svg
mockshot uml activity --project examples/diagrams/json/activity_mega.json -o /tmp/test.svg
mockshot uml state --project examples/diagrams/json/state_mega.json -o /tmp/test.svg
mockshot uml component --project examples/diagrams/json/component_mega.json -o /tmp/test.svg
mockshot uml deployment --project examples/diagrams/json/deployment_mega.json -o /tmp/test.svg

Always visually inspect output before committing.

License

MIT