Merge v0.2.5-1

.github/workflows/playwright.yml

@@ -35,8 +35,18 @@ jobs:
       run: pnpm install --frozen-lockfile
     - name: Build packages
       run: pnpm --filter @teammapper/mermaid-mindmap-parser run build
+    - name: Cache Playwright browsers
+      uses: actions/cache@v4
+      id: playwright-cache
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-browsers-${{ hashFiles('pnpm-lock.yaml') }}-webkit
     - name: Install Playwright Browsers
+      if: steps.playwright-cache.outputs.cache-hit != 'true'
       run: pnpm --filter teammapper-frontend exec playwright install webkit --with-deps
+    - name: Install Playwright system dependencies
+      if: steps.playwright-cache.outputs.cache-hit == 'true'
+      run: pnpm --filter teammapper-frontend exec playwright install-deps webkit
     - name: Run Playwright tests
       run: pnpm run migrate:dev && pnpm run test:e2e
       env:

.github/workflows/release.yml

@@ -46,7 +46,7 @@ jobs:
 
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
 

.gitignore

@@ -56,4 +56,10 @@ ca/*.key
 ca/*.req
 
 .env.prod
-.npmrc
+.npmrc
+
+# Speculatius - behavioral spec exploration output (regenerable)
+.speculatius/
+
+.playwright-mcp
+.mcp.json

AGENTS.md

@@ -0,0 +1,38 @@
+# Agents
+
+## Playwright MCP
+
+### Setup
+
+The Playwright MCP connects to a headless Chrome running in a separate Docker container (`chrome`) via CDP. Configuration is in `.mcp.json`. Example:
+
+```
+{
+    "mcpServers": {
+      "playwright": {
+        "command": "npx",
+        "args": ["@playwright/mcp@latest", "--cdp-endpoint", "http://<CHROME_DOCKER_IP>:9222"]
+      }
+    }
+}
+```
+
+### Networking
+
+- The app runs inside the `app` container, Chrome runs in the `chrome` container.
+- **Do not use `localhost` or the `app` hostname** to navigate — Chrome cannot resolve them properly.
+- **Chrome CDP rejects non-IP Host headers** — Chromium hardcodes a check that the HTTP `Host` header is an IP or `localhost`. There is no flag to disable this. Always use resolved IPs (not hostnames) in CDP endpoint URLs.
+- **Resolve container IPs first** with `getent hosts <container>`, then use the IP:
+
+```bash
+getent hosts app    # for navigation URLs
+getent hosts chrome # for CDP endpoint in .mcp.json
+```
+
+### Checklist
+
+1. Start the dev server: `pnpm run dev` (run in background)
+2. Wait for the server to be ready: `curl -s -o /dev/null -w "%{http_code}" http://localhost:4200`
+3. Resolve the app IP: `getent hosts app`
+4. Navigate with Playwright: `browser_navigate` to `http://<resolved-ip>:4200`
+5. Use `browser_snapshot` (preferred over screenshots) to inspect the page

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docker-compose.yml

@@ -32,10 +32,11 @@ services:
       AI_LLM_TPD: ${DOCKER_COMPOSE_APP_ENV_AI_LLM_API_TPD}
       JWT_SECRET: ${JWT_SECRET}
       YJS_ENABLED: ${YJS_ENABLED:-true}
-      LOG_LEVEL: ${LOG_LEVEL:-warn}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
 
       TESTING_PLAYWRIGHT_WS_ENDPOINT: "ws://playwright:9323"
       TESTING_PLAYWRIGHT_BASE_URL: "http://app:4200"
+      PLAYWRIGHT_MCP_CDP_ENDPOINT: "http://chrome:9222"
     ports:
       - "${APP_FRONTEND_PORT:-4200}:4200"
       - "${APP_BACKEND_PORT:-3000}:3000"
@@ -69,6 +70,15 @@ services:
       - "9323"
     command: ["npx", "playwright", "run-server", "--port=9323"]
 
+  chrome:
+    image: chromedp/headless-shell:latest
+    container_name: chrome
+    depends_on:
+      - app
+    expose:
+      - "9222"
+    # headless-shell listens on 9222 by default with --remote-debugging-address=0.0.0.0
+
 volumes:
   postgres_data:
   app_backend_node_modules:

openspec/changes/archive/2026-03-18-expand-import-export-spec/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-18

openspec/changes/archive/2026-03-18-expand-import-export-spec/design.md

@@ -0,0 +1,20 @@
+## Context
+
+Spec-only change, documenting existing behavior. The import-export capability already supports SVG, PNG, JPG, and PDF exports via a dropdown menu, and a ctrl+e keyboard shortcut. The existing OpenSpec spec only documents JSON and Mermaid import/export.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Document all observed export formats and the export keyboard shortcut in the OpenSpec spec
+
+**Non-Goals:**
+- No code changes — all behavior already exists
+- No changes to import specs or existing JSON/Mermaid export specs
+
+## Decisions
+
+No technical decisions required. This is a spec-only update documenting existing, verified behavior from Speculatius exploration.
+
+## Risks / Trade-offs
+
+No risks. The requirements are derived from Speculatius app exploration and match the explored spec's observations.

openspec/changes/archive/2026-03-18-expand-import-export-spec/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+The Speculatius app exploration discovered that the existing `import-export` spec only covers JSON and Mermaid import/export but omits image and document export formats (SVG, PNG, JPG, PDF) and the ctrl+e keyboard shortcut for export. These features are already implemented in the app but missing from the spec.
+
+## What Changes
+
+- **Expand import-export spec** with missing export requirements:
+  - Add SVG, PNG, JPG, and PDF export format scenarios to the export requirement
+  - Add ctrl+e keyboard shortcut scenario for triggering export
+
+## Non-goals
+
+- No code changes — all behavior already exists
+- No changes to import functionality specs
+- No changes to the existing JSON and Mermaid export scenarios
+
+## Capabilities
+
+### New Capabilities
+
+_(none)_
+
+### Modified Capabilities
+
+- `import-export`: Add export format scenarios (SVG, PNG, JPG, PDF) and keyboard shortcut (ctrl+e)
+
+## Impact
+
+- Spec-only change — no code, API, or dependency impact
+- `openspec/specs/import-export/spec.md` will be expanded with additional export scenarios

openspec/changes/archive/2026-03-18-expand-import-export-spec/specs/import-export/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Export keyboard shortcut
+The system SHALL trigger the export action when the user presses ctrl+e.
+
+#### Scenario: Export via keyboard shortcut
+- **WHEN** the user presses ctrl+e in the map editor
+- **THEN** the export action SHALL be triggered
+
+### Requirement: Export image and document formats
+The system SHALL allow exporting mind maps as SVG, PNG, JPG images and PDF documents via the export dropdown menu.
+
+#### Scenario: Export SVG
+- **WHEN** the user clicks "Image (.svg)" in the export menu
+- **THEN** the map SHALL be downloaded as an SVG image file
+
+#### Scenario: Export PNG
+- **WHEN** the user clicks "Image (.png)" in the export menu
+- **THEN** the map SHALL be downloaded as a PNG image file
+
+#### Scenario: Export JPG
+- **WHEN** the user clicks "Image (.jpg)" in the export menu
+- **THEN** the map SHALL be downloaded as a JPG image file
+
+#### Scenario: Export PDF
+- **WHEN** the user clicks "Document (.pdf)" in the export menu
+- **THEN** the map SHALL be downloaded as a PDF document

openspec/changes/archive/2026-03-18-expand-import-export-spec/tasks.md

@@ -0,0 +1,3 @@
+## 1. Update Spec
+
+- [ ] 1.1 Update import-export spec — no code changes required

openspec/changes/archive/2026-03-18-expand-mind-map-core-spec/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-18

openspec/changes/archive/2026-03-18-expand-mind-map-core-spec/design.md

@@ -0,0 +1,20 @@
+## Context
+
+Spec-only change, documenting existing behavior. The mind-map-core capability implements a landing page, info/deletion dialog, internationalization, canvas interaction model, and editor-based map creation, but the OpenSpec spec only documents basic creation and persistence. This change closes the documentation gap.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Document five observed behaviors in the OpenSpec mind-map-core spec
+
+**Non-Goals:**
+- No code changes — all behavior already exists
+- No changes to existing creation or persistence requirements
+
+## Decisions
+
+No technical decisions required. This is a spec-only update adding requirements that describe existing, verified behavior from Speculatius exploration.
+
+## Risks / Trade-offs
+
+No risks. All requirements match observed app behavior.

openspec/changes/archive/2026-03-18-expand-mind-map-core-spec/proposal.md

@@ -0,0 +1,33 @@
+## Why
+
+The Speculatius app exploration discovered five areas of the mind-map-core capability that are implemented but not documented in the OpenSpec spec: landing page, map info/deletion dialog, internationalization, canvas interaction model, and creating a new map from within the editor. The existing spec only covers basic map creation and persistence.
+
+## What Changes
+
+- **Expand mind-map-core spec** with five requirements documenting existing behavior:
+  - Landing page (hero section, feature cards, recently opened mindmaps)
+  - Map info and deletion dialog (version, deletion policy, delete button)
+  - Internationalization (8 supported languages)
+  - Mind map canvas interaction model (node selection enables toolbar, no-selection disables buttons)
+  - Create new map from editor (via "Cleans the map" button)
+
+## Non-goals
+
+- No code changes — all behavior already exists
+- No changes to existing map creation or persistence specs
+- No backend persistence requirements (already covered by existing spec)
+
+## Capabilities
+
+### New Capabilities
+
+_(none)_
+
+### Modified Capabilities
+
+- `mind-map-core`: Add landing page, map info/deletion, i18n, canvas interaction, and editor-based creation requirements
+
+## Impact
+
+- Spec-only change — no code, API, or dependency impact
+- `openspec/specs/mind-map-core/spec.md` will be expanded with five new requirement sections

openspec/changes/archive/2026-03-18-expand-mind-map-core-spec/specs/mind-map-core/spec.md

@@ -0,0 +1,64 @@
+## ADDED Requirements
+
+### Requirement: Create new map from editor
+The system SHALL allow users to create a new mind map from within the map editor via the "Cleans the map" button (note_add icon).
+
+#### Scenario: Create from editor
+- **WHEN** the user clicks the "Cleans the map" button in the map editor
+- **THEN** the user SHALL be navigated to `/map` which creates a new map
+
+### Requirement: Landing Page
+The system SHALL display a landing page with a description of the application and a call-to-action to create a mind map.
+
+#### Scenario: Hero section
+- **WHEN** the home page loads
+- **THEN** a hero section SHALL be displayed with the TeamMapper logo, tagline "The open-source web application to draw mind maps together", feature checklist, and a "Create mind map" button
+
+#### Scenario: Feature cards
+- **WHEN** the home page loads
+- **THEN** three feature cards SHALL be displayed: "Colors and images", "Radial tree", and "Uses", each with an image and description
+
+#### Scenario: Recently opened mindmaps
+- **WHEN** the user has previously opened maps
+- **THEN** a "Recently opened mindmaps" section SHALL show links to those maps with their root node name and last known deletion date
+
+#### Scenario: Empty recent maps
+- **WHEN** the user has not opened any maps
+- **THEN** the "Recently opened mindmaps" section SHALL be displayed with no entries
+
+### Requirement: Mind Map Canvas
+The system SHALL render the mind map as an interactive SVG canvas with clickable nodes.
+
+#### Scenario: Root node displayed
+- **WHEN** a newly created map loads
+- **THEN** a single "Root node" SHALL be displayed on the canvas
+
+#### Scenario: Node selection
+- **WHEN** the user clicks a node on the canvas
+- **THEN** that node SHALL become selected and the toolbar buttons SHALL become enabled
+
+#### Scenario: No selection state
+- **WHEN** no node is selected
+- **THEN** node-specific toolbar buttons (add, remove, copy, cut, paste, bold, italic, link, image, pictogram, detached node, group, hide children) SHALL be disabled
+
+### Requirement: Map Info and Deletion
+The system SHALL display map metadata and allow map deletion via an info dialog.
+
+#### Scenario: Info dialog
+- **WHEN** the user clicks the info button in the map editor
+- **THEN** a dialog titled "TeamMapper {version}" SHALL be displayed showing the app description, deletion policy, deletion date, GitHub link, and a "Delete mindmap" button
+
+#### Scenario: Deletion policy
+- **WHEN** the info dialog is displayed
+- **THEN** the text "Mindmaps will be deleted on this server after 30 days" SHALL be shown along with the specific deletion date
+
+### Requirement: Internationalization
+The system SHALL support multiple languages selectable from the footer or settings.
+
+#### Scenario: Language selector
+- **WHEN** the user opens the language selector
+- **THEN** options SHALL be available for: English, French, German, Italian, Traditional Chinese, Simplified Chinese, Spanish, Portuguese Brazil
+
+#### Scenario: Default language
+- **WHEN** a fresh session loads
+- **THEN** the language SHALL default to English

openspec/changes/archive/2026-03-18-expand-mind-map-core-spec/tasks.md

@@ -0,0 +1,3 @@
+## 1. Update Spec
+
+- [ ] 1.1 Update mind-map-core spec — no code changes required

openspec/changes/archive/2026-03-18-expand-settings-spec/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-18

openspec/changes/archive/2026-03-18-expand-settings-spec/design.md

@@ -0,0 +1,20 @@
+## Context
+
+Spec-only change, documenting existing behavior. The settings capability implements a full settings page with three tabs, keyboard shortcut access, detailed map options, and a list of created maps, but the OpenSpec spec only documents basic language change and map options toggle.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Document the full settings page structure, detailed map options, and map list tab in the OpenSpec spec
+
+**Non-Goals:**
+- No code changes — all behavior already exists
+- No changes to existing language or basic map options requirements
+
+## Decisions
+
+No technical decisions required. This is a spec-only update documenting existing, verified behavior from Speculatius exploration.
+
+## Risks / Trade-offs
+
+No risks. All requirements match observed app behavior.

openspec/changes/archive/2026-03-18-expand-settings-spec/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+The Speculatius app exploration discovered that the existing `settings` spec only covers basic language change and map options toggle, but omits the settings page navigation structure (3 tabs, close button, alt+s shortcut), detailed map options fields (center-on-resizing, font size step, default node names, show-linktext), and the "List of created maps" tab. These features are already implemented but not documented.
+
+## What Changes
+
+- **Expand settings spec** with three requirements documenting existing behavior:
+  - Settings page navigation (tab structure, keyboard shortcut, close button)
+  - Detailed map options fields (center-on-resizing, font size step/defaults, default node names, show-linktext)
+  - List of created maps tab (recently opened maps with deletion dates)
+
+## Non-goals
+
+- No code changes — all behavior already exists
+- No changes to existing language change or basic map options specs
+
+## Capabilities
+
+### New Capabilities
+
+_(none)_
+
+### Modified Capabilities
+
+- `settings`: Add settings navigation, detailed map options, and map list requirements
+
+## Impact
+
+- Spec-only change — no code, API, or dependency impact
+- `openspec/specs/settings/spec.md` will be expanded with three new requirement sections