tinta-mcp 0.2.2__tar.gz

tinta_mcp-0.2.2/.agents/AGENTS.md

@@ -0,0 +1,60 @@
+# Tinta MCP agent guide
+
+Tinta is a Model Context Protocol (MCP) server that enables AI assistants to control running Inkscape instances in real time via D-Bus.
+
+## Repository overview
+
+- `tintamcp/`: Python MCP server package (`fastmcp`). Runs in the user's external Python environment, exposes tools, and translates requests into D-Bus calls.
+- `extension/`: Inkscape extension (`tinta_mcp.py`, `tinta_mcp.inx`, and `tinta_mcp_ops/`). Runs inside Inkscape's internal Python interpreter when triggered by D-Bus.
+- `tests/`: Automated unit tests and live D-Bus smoke tests using `pytest`.
+- `scripts/`: Setup scripts for Windows (`install_windows.ps1`, `install_windows.bat`) and Linux/WSL (`install_linux.sh`).
+- `.agents/`: Project rules, guidelines, and skills for AI assistants and contributors.
+- `.github/workflows/`: CI matrix tests, security audits, headless D-Bus integration tests, and release packaging.
+
+## Core rules and invariants
+
+1. Runtime separation:
+   `tintamcp` must remain pure Python. Never add `inkex`, `lxml`, `pycairo`, or `pygobject` to `[project.dependencies]` in `pyproject.toml`. The `inkex` module is only imported inside `extension/` because it is provided by Inkscape at runtime.
+2. D-Bus identifier:
+   The registered D-Bus action name is strictly `org.tinta.mcp`. Do not introduce backwards-compatibility aliases (`inkmcp`).
+3. Cross-platform parity:
+   Support both Windows and Linux. On Windows, D-Bus calls use Inkscape's bundled `gdbus.exe`. On Linux, D-Bus calls use the system session bus `gdbus`. IPC lives under `%LOCALAPPDATA%\Temp\tintamcp\<user>` on Windows, or a verified private `$XDG_RUNTIME_DIR/tintamcp` with `/tmp/tintamcp-<uid>` fallback on Linux.
+4. Security and sanitization:
+   Validate XML element and attribute names using `is_valid_xml_name()`. Escape attribute values properly before inserting into SVG trees. Python code execution and textual command tools are not supported. Never evaluate client-provided Python with `exec`/`eval` or resolve operation names to arbitrary Python callables. Use fixed extension handlers receiving structured data; operation names and SVG element tags are separate fields.
+5. Code quality gates:
+   When modifying Python code (`extension/`, `tintamcp/`, `tests/`) or dependencies (`pyproject.toml`), verify that all quality gates pass:
+   ```bash
+   uv run ruff check extension tintamcp tests
+   uv run ruff format --check extension tintamcp tests
+   uv run pyright
+   uv run pytest
+   uv run pip-audit
+   ```
+   Pure documentation edits (such as updating `.md` files) do not require running Python test or lint gates.
+
+## Technical prose and documentation style
+
+When writing documentation, guides, commit messages, or agent responses:
+- State facts directly without rhetorical staging (*not X but Y*, fake alternatives, or dramatic one-line closers).
+- Use sentence case for headings, avoid decorative emojis, and do not divide sections with horizontal rules (`---`).
+- Do not use em dashes (`—`) or double hyphens (`--`) as universal connectors. Use colons, commas, periods, or parentheses instead.
+- Write list items as natural sentences without forcing a bold title and colon on every bullet.
+- Maintain a neutral, factual tone without marketing filler or AI buzzwords (*robust*, *seamless*, *testament*, *pivotal*, *delve*, *cutting-edge*, *effortless*).
+
+## Project rules and references
+
+- Architecture and IPC boundaries: [rules/architecture.md](rules/architecture.md)
+
+## Project skills
+
+- `mcp-tool-builder` ([skills/mcp-tool-builder/SKILL.md](skills/mcp-tool-builder/SKILL.md)): Workflow for adding, modifying, and testing MCP tools for Inkscape.
+- `tinta-designer` ([skills/tinta-designer/SKILL.md](skills/tinta-designer/SKILL.md)): Best practices and technical guidelines for creating and editing vector graphics in Inkscape via Tinta.
+- `tinta-dev-workflow` ([skills/tinta-dev-workflow/SKILL.md](skills/tinta-dev-workflow/SKILL.md)): Development standards, `uv` environment management, Conventional Commits, and CI quality gates.
+
+## Releasing a new version
+
+1. Bump version in `pyproject.toml` (`version = "X.Y.Z"`).
+2. Verify quality gates pass: `uv run pytest && uv run ruff check extension tintamcp tests && uv run pyright`.
+3. Commit using Conventional Commits: `git commit -am "chore(release): bump version to X.Y.Z"`.
+4. Tag and push: `git tag vX.Y.Z && git push origin main --tags`.
+5. GitHub Actions builds wheels, packages `tinta-extension.zip`, and creates the GitHub Release automatically.

tinta_mcp-0.2.2/.agents/rules/architecture.md

@@ -0,0 +1,62 @@
+---
+trigger: manual
+---
+
+# Architecture and invariants
+
+## Process and runtime boundaries
+
+```
+[ AI Assistant / Client ]
+           │
+           â–¼ (MCP protocol over stdio)
+   [ tintamcp server ]  <-- Pure Python, managed by uv (fastmcp)
+           │
+           â–¼ (writes request JSON to user IPC folder)
+   [ gdbus / session bus ]
+           │
+           â–¼ (Action activation: org.tinta.mcp)
+   [ Inkscape process ]
+           │
+           â–¼ (runs extension/tinta_mcp.py via internal inkex)
+   [ Open SVG document ]
+```
+
+- Server process (`tintamcp`): Orchestrates communication, tool definitions, schemas, and parameter validation. Does not touch SVG directly.
+- Extension process (`extension`): Inkscape executes this inside its GTK event loop. It stages DOM mutations, serializes the SVG, then publishes the response JSON.
+
+## IPC protocol invariants
+
+- The D-Bus action has no parameters. One process lock protects the shared request slot across server processes; a per-connection thread lock also serializes threads.
+- The server atomically publishes `mcp_params.json` and `pending_request.json`; the extension claims the slot by exclusively creating `mcp_processing.json` before it reads the request.
+- Request format:
+  ```json
+  {
+    "protocol_version": 1,
+    "session_id": "32 lowercase hexadecimal characters",
+    "request_id": "32 lowercase hexadecimal characters",
+    "request": {
+      "operation": "create-element" | "modify-elements" | "get-info" | "...",
+      "attributes": { ... }
+    }
+  }
+  ```
+- Response path is derived from `request_id` as `mcp_response_<request_id>.json`; the request cannot choose a path. Responses repeat the version and both identifiers. The extension writes a temporary sibling and atomically renames it into place.
+- The extension stages document mutations on a deep copy and publishes an error without using that copy if a handler fails. `save_raw()` serializes the SVG before it writes the response.
+- Legacy requests with only a top-level `tag`, including `execute-code`, are rejected. There is no arbitrary Python or textual-command execution.
+- Server and extension must be deployed together. Nesting the operation means a phase 1 extension sees no top-level operation and cannot execute a stale-format mutation. The server sends protocol version 1 and rejects missing or mismatched response identifiers, including the operation name.
+- The server polls the derived response path for 5 seconds after D-Bus activation. Timeout, malformed response, or D-Bus failure means the outcome is unknown, not cancelled. The pending request remains on disk; later calls first reconcile its response and refuse to overwrite unresolved files.
+- IPC uses `$XDG_RUNTIME_DIR/tintamcp` only when its owner and permissions are private, otherwise `/tmp/tintamcp-<uid>` with mode 0700. Windows uses the current user's local application data temp directory. Do not add global-temp fallbacks or caller-supplied IPC paths.
+
+## Tool pipeline design
+
+- Prefer atomic operations where possible.
+- The `create_elements` tool handles creation, canvas resizing, viewport fitting (`fit_canvas`), selection highlighting (`select_created`), and preview rendering (`return_preview`) in a single round-trip.
+- Avoid forcing the LLM to make multiple serial round-trips for common design workflows.
+
+## Native GTK export actions
+
+- Canvas preview exports use Inkscape GTK actions (`export-type`, `export-filename`, `export-overwrite`, `export-area-page`, `export-do`) triggered via `gdbus`.
+- Never spawn a secondary headless Inkscape process to render previews: native actions take ~0.5s versus ~3.0s for CLI spawns.
+- Every native preview action must be prepared successfully before `export-do`. Use a unique IPC destination, quote GVariant strings, cap the largest PNG dimension, and validate the complete PNG before returning it. A preview failure after an edit is a warning alongside the applied edit result.
+- A successful D-Bus transport call is not an operation result. Extension errors must become MCP tool errors; inspection returns all reported metadata and selected elements without silent truncation.

tinta_mcp-0.2.2/.agents/skills/mcp-tool-builder/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: mcp-tool-builder
+description: "Step-by-step guide for creating, modifying, and testing MCP tools for Inkscape in Tinta."
+---
+
+# MCP tool builder for Tinta
+
+Use this skill when adding a new tool or modifying an existing tool in Tinta.
+
+## Dual-runtime architecture
+
+Every tool in Tinta bridges two distinct environments:
+
+1. Host server (`tintamcp/`): Runs in external Python with FastMCP. Defines the tool signature, validates types, atomically writes a versioned request to the user's IPC directory, and calls D-Bus.
+2. Inkscape extension (`extension/`): Runs inside Inkscape's Python context via `inkex`. Claims and validates the IPC request, stages document edits, serializes the SVG, and atomically writes a correlated response.
+
+```
+[Client / LLM] ──> FastMCP (@mcp.tool) ──> IPC Request File ──> gdbus ──> [Inkscape Extension] ──> SVG DOM
+```
+
+## Step 1: Define the tool in `tintamcp/server.py`
+
+Register the tool on the `mcp` instance using clear, type-annotated parameters and concise docstrings designed for LLM consumption:
+
+```python
+@mcp.tool()
+def my_new_tool(element_id: str, radius: float = 10.0, color: str = "#000000") -> str:
+    """Short description of what the tool accomplishes on the canvas.
+
+    Args:
+        element_id: Unique identifier for the SVG element.
+        radius: Radius in user units (default 10.0).
+        color: Hex or CSS color string (e.g. '#ff0000').
+    """
+    payload = {
+        "operation": "my-operation",
+        "attributes": {
+            "id": element_id,
+            "radius": str(radius),
+            "color": color,
+        },
+    }
+    return str(dispatch_operation(payload))
+```
+
+### Design guidelines for MCP tools
+
+- Use snake_case for Python parameters. Tinta automatically normalizes snake_case to kebab-case SVG attributes (`stroke_width` -> `stroke-width`).
+- Provide sensible defaults to reduce round-trips for common actions.
+- Prefer atomic operations. When an operation involves creating elements, fitting canvas, or generating previews, combine them into a single round-trip (see `create_elements`).
+
+### Docstring design for LLM consumers
+
+Tool docstrings are injected directly into the client LLM system prompt. Follow these guidelines to maximize tool calling accuracy and minimize token overhead:
+- State actions directly using imperative mood in the first line (`"Create an SVG rectangle."`, not `"This tool allows the user to seamlessly create..."`).
+- Avoid marketing filler and buzzwords (*robust*, *seamless*, *powerful*, *effortless*, *cutting-edge*, *comprehensive*).
+- Document units and formats explicitly (pixels, percentages, hex colors) and valid ranges in the `Args:` section.
+- Explain non-obvious defaults concisely so the LLM can plan its workflow in fewer calls.
+
+## Step 2: Implement the operation in `extension/`
+
+Operations live under `extension/tinta_mcp_ops/`:
+- Shape and element creation: `extension/tinta_mcp_ops/element_mapping.py`
+- Manipulation and attributes: `extension/tinta_mcp_ops/document_operations.py`
+
+### Handling the action in `extension/tinta_mcp.py`
+
+Register a fixed handler in `DOCUMENT_OPERATIONS`, called by `ElementCreator.handle_operation`. Never generate Python source or expose an interpreter. Operation names are independent of SVG tags. For queries handled by the extension:
+
+```python
+if operation == "my-operation":
+    # 1. Access the open document DOM via self.svg
+    elem = self.svg.getElementById(attributes.get("id"))
+
+    # 2. Mutate DOM using inkex elements
+    # 3. Return response data; the extension publishes it after SVG serialization.
+```
+
+The extension never accepts a response path from an operation. Requests use protocol version 1 with generated session and request IDs; responses use the corresponding derived path.
+
+## Step 3: Test and debug
+
+### Manual D-Bus trigger (Windows and Linux)
+
+Verify that Inkscape responds over the session bus:
+
+Windows (PowerShell):
+```powershell
+$gdbus = "C:\Program Files\Inkscape\bin\gdbus.exe"
+& $gdbus call --session --dest org.inkscape.Inkscape --object-path /org/inkscape/Inkscape --method org.gtk.Actions.List | Select-String "org.tinta.mcp"
+```
+
+Linux / WSL (Bash):
+```bash
+gdbus call --session --dest org.inkscape.Inkscape --object-path /org/inkscape/Inkscape --method org.gtk.Actions.List | grep org.tinta.mcp
+```
+
+### Automated integration test
+
+Add a test in [tests/test_dbus_smoke.py](../../../tests/test_dbus_smoke.py):
+
+```python
+def test_my_new_tool_live():
+    result = my_new_tool(element_id="test_item_1", radius=15.0)
+    assert "success" in result.lower()
+```
+
+Run tests locally:
+```bash
+uv run pytest
+```
+
+Use `uv run pytest tests/test_dbus_smoke.py --live-inkscape -v` for live tests. The fixture must own an isolated process/profile/document; never target the user's running session.

tinta_mcp-0.2.2/.agents/skills/tinta-designer/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: tinta-designer
+description: "Best practices, workflows, and technical guidelines for creating and editing vector graphics in Inkscape via Tinta MCP."
+---
+
+# Tinta designer workflow
+
+Use this skill when creating, modifying, or inspecting vector illustrations, diagrams, icons, or layouts in an open Inkscape session.
+
+## Core workflow
+
+### 1. Inspect existing state
+Before creating or editing graphics, verify the current canvas state:
+- Call `get_document_info` to inspect canvas dimensions, viewBox coordinates, and existing element counts.
+- Call `get_selection` if the user refers to "selected items", "this shape", or wants to modify whatever is currently highlighted in the Inkscape UI.
+- Do not clear the canvas unless the user explicitly asks to start from scratch or clear the document.
+
+### 2. Batch operations using `create_elements`
+Avoid making multiple sequential tool calls to insert shapes one by one. Use `create_elements` to submit a structured batch:
+- Combine element definitions, canvas fitting, and preview rendering in a single request.
+- Use `fit_canvas=True` with `fit_padding` when drawing a composition whose final bounding box should define the page boundaries.
+- Set `return_preview=True` to immediately obtain an image preview of the resulting render.
+
+### 3. Verify with visual feedback
+Always inspect the visual result before concluding a design task:
+- Use the preview returned by `create_elements(return_preview=True)` or call `export_preview()`.
+- Check for overlapping text, clipping at viewBox boundaries, or unintended layer stacking.
+- If an adjustment is needed, modify elements by ID with `modify_elements` (using `return_preview=True` for instant visual verification) rather than redrawing the entire canvas.
+
+## Technical SVG guidelines for Inkscape
+
+### Document hierarchy and grouping
+Organize elements into logical groups using `<g id="...">`:
+- Group related shapes together (e.g. `header_group`, `chart_bars`, `icon_background`).
+- Grouped elements appear cleanly in Inkscape's Objects and Layers panel (`Ctrl+Shift+L`), allowing the user to select, hide, or transform components easily.
+- Assign meaningful, unique IDs to major elements so they can be modified later without guessing.
+
+### Z-order and stacking
+In SVG, rendering order follows document order:
+- Elements defined earlier in the payload are drawn below later elements.
+- Always declare background rectangles, cards, or base shapes first.
+- Declare decorative details, strokes, icons, and text elements last.
+
+### Primitive shapes versus paths
+- Use native primitives (`<rect>`, `<circle>`, `<ellipse>`, `<line>`) whenever possible. In Inkscape, native primitives retain parametric handles (e.g. dragging corner radius on a rectangle).
+- Use `<path>` for custom curves, logos, irregular polygons, or arrows where primitives are insufficient.
+
+### Text positioning and baseline alignment
+In SVG, the `y` coordinate of a `<text>` element refers to the typographic baseline, not the top-left bounding box corner:
+- If placing text at the top of a container at `y=0`, the text will render above the visible area.
+- Either offset `y` downwards by at least the font size (e.g. `y=24` for a `20px` font) or set `dominant-baseline="hanging"`.
+- Use cross-platform fallback font stacks such as `system-ui, sans-serif, Arial, Helvetica, DejaVu Sans` so text renders reliably on both Windows and Linux installations.
+
+### Viewport and coordinate consistency
+- Work within a consistent coordinate system defined by the `viewBox`.
+- When sizing rectangles or positioning icons, calculate relative offsets from the parent group or anchor position rather than placing arbitrary coordinates across the canvas.

tinta_mcp-0.2.2/.agents/skills/tinta-dev-workflow/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: tinta-dev-workflow
+description: "Developer and AI agent workflow for dependency management, code quality gates, and conventional commits in Tinta."
+---
+
+# Tinta development and quality workflow
+
+Use this skill for local environment setup, running quality gates, and crafting commits that pass CI.
+
+## Environment management with uv
+
+Tinta uses `uv` for fast, reproducible dependency resolution.
+
+### Basic commands
+
+```bash
+# Sync all dependencies (runtime + dev tools)
+uv sync --all-groups
+
+# Add a runtime dependency (must be pure Python, no C/inkex)
+uv add <package-name>
+
+# Add a development tool (linter, test helper)
+uv add --group dev <package-name>
+
+# Run commands within the managed environment
+uv run pytest
+uv run ruff check extension tintamcp tests
+```
+
+### Windows and WSL shared drive tip
+
+When developing across both Windows and WSL on a shared drive:
+- Windows `.venv` uses `.venv/Scripts/python.exe`.
+- Linux `.venv` uses `.venv/bin/python`.
+- Running `uv sync` switches between them in 1-2 seconds because all dependencies are pure Python wheels.
+
+## Quality gates checklist
+
+Run these checks when modifying Python code (`extension/`, `tintamcp/`, `tests/`) or dependencies (`pyproject.toml`). Pure documentation edits do not require running test or lint gates.
+
+```bash
+# 1. Linting and import sorting
+uv run ruff check extension tintamcp tests
+
+# 2. Code formatting
+uv run ruff format --check extension tintamcp tests
+
+# 3. Static type analysis
+uv run pyright
+
+# 4. Test suite and coverage report
+uv run pytest
+
+# 5. Dependency security audit
+uv run pip-audit
+```
+
+To automatically format files:
+```bash
+uv run ruff format extension tintamcp tests
+uv run ruff check --fix extension tintamcp tests
+```
+
+## Conventional Commits standard
+
+All PR titles and commit messages must follow the Conventional Commits specification.
+
+### Format
+
+```text
+<type>(<scope>): <short description in imperative mood>
+
+[optional body explaining motivation and context]
+
+[optional footer, e.g. BREAKING CHANGE or Closes #123]
+```
+
+### Allowed types
+
+- `feat`: New feature or MCP tool (e.g. `feat(tools): add canvas_rotate tool`)
+- `fix`: Bug fix in server, extension, or installer (e.g. `fix(ipc): handle spaces in username path`)
+- `docs`: Documentation updates (e.g. `docs: clarify WSL setup in README`)
+- `refactor`: Code restructuring without functional changes (e.g. `refactor(parser): extract xml validation`)
+- `perf`: Performance improvement (e.g. `perf(export): use native GTK export actions`)
+- `test`: Adding or updating tests (e.g. `test(dbus): add smoke test for element deletion`)
+- `ci`: CI/CD workflow changes (e.g. `ci: add security audit gate`)
+- `chore`: Tooling, dependency, or version updates (e.g. `chore(deps): update fastmcp to 4.1.0`)
+
+### Rules
+
+- Use lower case for type and scope.
+- Use imperative present tense (`add`, not `added` or `adds`).
+- Do not add a period at the end of the subject line.

tinta_mcp-0.2.2/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{bat,cmd,ps1}]
+end_of_line = crlf
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

tinta_mcp-0.2.2/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+*.png binary

tinta_mcp-0.2.2/.github/actionlint.yaml

@@ -0,0 +1,4 @@
+# Ubuntu 26.04 is a hosted image not yet included in actionlint's built-in labels.
+self-hosted-runner:
+  labels:
+    - ubuntu-26.04

tinta_mcp-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,194 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "**.md"
+      - "assets/**"
+      - ".gitignore"
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+      - reopened
+    branches:
+      - main
+    paths-ignore:
+      - "**.md"
+      - "assets/**"
+      - ".gitignore"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  pull-requests: read
+  contents: read
+
+env:
+  PYTHONUTF8: "1"
+  PYTHONIOENCODING: utf-8
+
+jobs:
+  pr-title:
+    name: Validate PR Title (Conventional Commits)
+    runs-on: ubuntu-26.04
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Validate PR Title
+        uses: amannn/action-semantic-pull-request@v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false
+
+  lint:
+    name: Lint, Format & Type Check
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Check code formatting (ruff format)
+        run: uv run ruff format --check extension tintamcp scripts tests
+
+      - name: Check lints and imports (ruff check)
+        run: uv run ruff check extension tintamcp scripts tests
+
+      - name: Check static types (pyright)
+        run: uv run pyright
+
+      - name: Validate Linux installer syntax
+        run: bash -n scripts/install_linux.sh
+
+  audit:
+    name: Dependency Security Audit
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Audit dependencies for known CVEs
+        run: uv run pip-audit
+
+  test:
+    name: Test (${{ matrix.os }}, Py ${{ matrix.python-version }})
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-26.04, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --all-groups --python ${{ matrix.python-version }}
+
+      - name: Validate Windows installer syntax
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: |
+          $tokens = $null
+          $parseErrors = $null
+          [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path scripts/install_windows.ps1), [ref]$tokens, [ref]$parseErrors) | Out-Null
+          if ($parseErrors.Count) {
+            $parseErrors | ForEach-Object { Write-Error $_.Message }
+            exit 1
+          }
+
+      - name: Run test suite with coverage
+        run: uv run pytest
+
+      - name: Upload coverage artifact
+        if: matrix.os == 'ubuntu-26.04' && matrix.python-version == '3.13'
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: coverage-report
+          path: coverage.xml
+          retention-days: 7
+
+  dbus-e2e:
+    name: Headless D-Bus E2E Test (Linux)
+    needs: lint
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7.0.1
+
+      - name: Install Inkscape and headless test tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y inkscape libglib2.0-bin xvfb dbus-x11
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Run live tests in isolated profiles and documents
+        run: timeout 15m xvfb-run -a dbus-run-session uv run pytest tests/test_dbus_smoke.py --live-inkscape -v --junitxml=live-inkscape-results.xml
+
+      - name: Upload live test results
+        if: always()
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: live-inkscape-results
+          path: live-inkscape-results.xml
+          if-no-files-found: ignore
+          retention-days: 7