* chore(ci): release fires on workflow_dispatch, not on every CI pass
Replaced workflow_run trigger (fired automatically when CI completed
on main) with workflow_dispatch. The full semantic-release automation
is preserved — bump detection, version commit, tag, GitHub Release,
NPM + Docker publish — but now runs only when explicitly triggered.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(transport): add Streamable HTTP mode — one shared process for all MCP clients (v1.2.0)
Add MCP_TRANSPORT=http mode backed by StreamableHTTPServerTransport. Each
Claude Code session connects to the shared long-lived process via HTTP (port
3031 by default) instead of spawning a new stdio process per session, eliminating
per-session process multiplication. Sessions are isolated by mcp-session-id header.
Also refactor src/index.ts to extract createMcpServer()/registerHandlers() for
clean per-session server instantiation, and upgrade fs.writeFileSync/readFileSync
calls to fs.promises async variants in export/import tool handlers.
9 new tests cover transport resolution, session isolation, teardown, and
startMcpHttpServer. All 528 tests pass. Bumps v1.1.0 → v1.2.0.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: newblacc <newblacc@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(canvas): native field preservation, label materialization, batch workspace delete
- fillNativeFields() + repairContainerBinding() in db layer ensure every
element stored in SQLite is a complete, round-trippable Excalidraw element
with correct containerId ↔ boundElements bidirectional binding
- materializeLabel() in server.ts: shapes with label.text/text produce a
native bound text element at write time (create, update, batch) so text
follows its container when moved — matches VSCode Excalidraw extension behavior
- Batch workspace UI: Select/Unselect All, per-row checkboxes, Delete N
workspaces button with confirmation
- POST /api/tenants/batch-delete: delete up to 50 tenants in one request
- 42 new backend tests; 519 total passing
- Bump version 1.0.6 → 1.1.0
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(tests): update e2e assertions for label materialization
phase2-regressions: label is now a native bound text element
(id: pos-stable-1-label) — check bound text element text instead
of container.label?.text which is no longer stored.
sync-flows FTS: search now matches the bound text element (fts-el-label)
rather than the container — accept either id as valid match.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
The file transport defaulted to writing excalidraw.log relative to
process.cwd(), polluting every project directory where the MCP server
started. Console transport already handles warn+error to stderr.
File logging is now opt-in: set LOG_FILE_PATH to enable it.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace Unix-only `2>/dev/null || true` with a `node -e` inline script
that silently ignores better-sqlite3 rebuild failures on all platforms.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@modelcontextprotocol/sdk@1.26.0 uses zod/v4 APIs (specifically
z.literal().value getter). When installed globally, npm shared the
project's zod@3.25.5 instead of the SDK's nested zod@4.3.6; the
3.25.5 v4 compat shim lacks the .value getter, throwing
'Schema method literal must be a string' on startup.
Also updates z.record(z.any()) to z.record(z.string(), z.any())
for zod v4 strict record key typing.
446/446 tests passing.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ElementSharedFieldsSchema in server.ts was silently stripping textAlign,
verticalAlign, and containerId on every POST/PATCH, causing bound text
inside containers to lose centering after a sync round-trip.
- Add missing fields to ElementSharedFieldsSchema (server.ts)
- Add textAlign?, verticalAlign?, containerId? to ServerElement (types.ts)
- Set textAlign: "center", verticalAlign: "top" on MCP subtitle elements (index.ts)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Block CONNECTING state in WS guard to prevent second connection seeding
knownContainerIdsRef before element_created fires
- Call handleCanvasChange() explicitly after element_created updateScene
(CaptureUpdateAction.NEVER suppresses onChange in Excalidraw 0.18)
- E2E: curved arrow stays deformable after sync round-trip
- E2E: auto-title injection test now reliably passes
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Default font changed to Nunito (id 6)
- Containers auto-inject "Title" + "Text here" subtitle on draw (grouped)
- MCP create_element defaults to title/subtitle card layout for containers
- Sync preserves element geometry (x/y/width/height) across refreshes
- normalizeForBackend preserves native bound text instead of collapsing to label.text
- Rate limits raised to 500 req/15min general, 30 req/min sync writes
- Draggable "Font px" widget with localStorage position persistence
- Left panel widened for full Opacity visibility
- Updated rate-limit tests to match new limits (30 write, 500 general)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
convertToExcalidrawElements silently dropped label.text on reload.
Added expandLabelsToNative() that pre-expands server-format labels
into native Excalidraw bound text elements before the scene is set,
ensuring labels survive DB round-trips.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Update lastSyncedElementsRef on every WS-applied scene change so
auto-sync does not revert MCP writes back to stale browser state
- Fix labeled container updates (rect/ellipse/diamond/arrow) to use
convertToExcalidrawElements with bound-text ID transplant, preventing
text clipping and empty labels after update
- Fix standalone text element updates to write into text/originalText
so Excalidraw renders the new value immediately
- Fix convertTextToLabel to handle arrows and empty string text values
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds postinstall script to rebuild better-sqlite3 native bindings for
the current Node.js version. Fixes ERR_DLOPEN_FAILED when installing
via npx on a different Node version than was used to publish.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- 9 backend security test files (auth, headers, rate-limit, middleware
order, smoke, validation, WS auth, integration bootstrap)
- 1 e2e test (clear-preference)
- SECURITY.md policy doc
These files powered the 369-test suite but were never committed.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- actions/upload-artifact: replace stale v3 SHA (pinned as v4.6.2) with @v4
- docker/metadata-action: replace non-existent SHA 902fa8ec7 with @v5
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Deletions made in the UI were silently lost on page reload because the sync
baseline (lastSyncedElementsRef) was never populated after initial load,
making the delta algorithm unable to detect removed elements. Additionally,
import_scene and restore_snapshot used a non-atomic clear+create pattern
that could permanently lose all canvas data if the batch create failed
after clearing, and duplicate_elements copied stale binding references
pointing to original element IDs instead of remapped duplicates.
🔧 Sync baseline restoration:
- Populate deletion-detection baseline on every server-to-client data path
(page load, delta resync, hello handshake, initial elements broadcast)
- Establish sync version and hash baselines to prevent phantom re-syncs
🛡️ Data-loss prevention:
- Backup current scene before destructive clear in replace-mode operations
- Atomic restore from backup when subsequent batch create fails
- Remap all binding references (start/end IDs, boundElements, containerId)
to new IDs during element duplication
✅ Comprehensive test coverage (154 new tests, 344 total):
- Delta sync flows including deletion persistence and bidirectional sync
- Multi-tenant element/sync/WebSocket isolation
- Arrow binding resolution across all shape types and edge cases
- MCP tool integration covering backup-restore and binding remapping
- Input validation and security boundary testing
- Frontend sync algorithm unit tests reproducing the exact regression
🎯 Eliminates the most critical data-integrity risks: deletions now
persist reliably, destructive operations are rollback-safe, and the
full test suite provides regression coverage for every sync path.
Fix 6 bugs discovered during MCP tool usage:
1. syncToCanvas error handling: Distinguish network errors (return null)
from API errors (re-throw with actual message). Fixes misleading
"HTTP server unavailable" on batch_create_elements.
2. USER_PREFS fallbacks: create_element and batch_create_elements now
apply fontFamily/roughness/fontSize/strokeWidth from preferences.json
when not explicitly provided by the caller.
3. Hello handshake: Frontend sends `hello` on tenant_switched and handles
`hello_ack`. Server resolves projectId from tenantId when absent.
Fixes WS connections being registered under wrong scope.
4. Serialized broadcasts: Add serializedBroadcastWithAck() that queues
broadcasts per tenant/project scope. Prevents race condition where
parallel MCP create_element calls produce overlapping WS messages
that clobber each other in the frontend.
5. Viewport screenshot: get_canvas_screenshot passes captureViewport=true,
frontend captures DOM canvas via toDataURL() instead of exportToBlob()
which always rendered the full scene bounding box.
6. Viewport animate:false: set_viewport uses animate:false for instant
positioning, preventing mid-animation screenshot captures.
Tests: 14 new tests (8 API, 6 WS) + 9 E2E specs covering all fixes.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Implement a complete sync architecture overhaul (12 tasks) replacing the flat
WebSocket broadcast with scoped, acknowledged delivery:
**Backend (server.ts, db.ts, types.ts, index.ts):**
- Scoped connection registry: Map<tenant, Map<project, Set<ClientConnection>>>
- Hello handshake: WS clients identify tenant/project, server responds with scoped elements
- broadcastToScope() replaces global broadcast for element mutations
- broadcastWithAck() waits for browser ACK before returning syncedToCanvas status
- sync_version: monotonic counter per project, stamped on every mutation
- Delta sync v2: POST /api/elements/sync/v2 for incremental sync with version tracking
- GET /api/sync/version endpoint
- Honest syncedToCanvas + canvasStatus in all mutation responses
- Fixed silent try/catch in tenant switch verification
**Frontend (App.tsx):**
- ACK sending after every updateScene() with element verification
- Delta sync v2 integration in syncToBackend()
- Gap detection: triggers resync when sync_version gaps are detected
- lastSyncVersion tracking via refs + localStorage persistence
**Tests (40 new tests, 168 total):**
- db.test.ts: +11 tests for sync_version CRUD, scoping, getChangesSince
- ws.test.ts: +8 tests for hello handshake, scoped broadcast, ACK model
- api.test.ts: +10 tests for sync/v2, sync/version, canvasStatus responses
- helpers.test.ts: +11 tests for isImageElement, normalizeImageElement, restoreBindings
- canvas.spec.ts: +8 e2e tests including full ACK pipeline verification
- Fixed stale tenant state bug in api.test.ts beforeEach
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Font family IDs were duplicated across 5 files (types.ts, setup.ts,
index.ts, SKILL.md, preferences.example.json) with inconsistent
mappings — Comic Shanns was 4 in some places but actually 8 in
Excalidraw source. This caused wrong fonts to render on canvas.
Fix: create src/font-families.json as the canonical font data, import
it in types.ts, and derive all other references from it. Static docs
now point to the JSON file instead of duplicating the mapping.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Users are now prompted to choose their preferred font family and roughness
style during both `setup` and `update`. Preferences are saved to
~/.claude/skills/excalidraw-skill/preferences.json, which the MCP server
already reads at startup via loadPreferences(). This ensures third-party
users who install via npx get preferences configured before first use.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a preference system that lets users configure default font, roughness,
fontSize, and strokeWidth — with three scopes (session/folder/global).
Skill layer (Step 1 in SKILL.md):
- Reads .claude/excalidraw-preferences.json (folder) then
~/.claude/skills/excalidraw-skill/preferences.json (global)
- If neither exists, prompts user interactively on first use
- Session-only scope keeps preferences in-memory without saving
Server layer (index.ts):
- loadPreferences() reads the same files at startup
- Replaces hardcoded fontFamily ?? 1 with USER_PREFS.fontFamily
- Folder-level preferences override global; user values override both
Also ships preferences.example.json as a template (preferences.json
is gitignored).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The excalidraw-skill was not being auto-invoked when users prompted
Claude to draw diagrams, despite being installed. Claude would call
Excalidraw MCP tools directly, bypassing the skill's critical sizing
formulas and verification workflow — producing broken diagrams with
invisible arrows, truncated text, and overlapping elements. The root
cause is that Claude Code's skill system is advisory: when direct MCP
tools or built-in Bash instructions are available, Claude skips skill
consultation entirely.
🔧 Skill description rewrite:
- Lead with "MANDATORY prerequisite" to assert priority over raw MCP tools
- Add user-intent trigger keywords (draw, visualize, sketch, diagram)
- Name specific consequences of skipping the skill
- List common diagram types for semantic matching
🏗️ Setup/update auto-directives:
- Write marked CLAUDE.md sections during skill install and update
- Write Cursor .mdc rules with alwaysApply for Cursor users
- Use HTML comment markers for idempotent append-or-replace on updates
- Non-fatal directive writing — skill installs even if directive fails
🎯 Two-layer defense ensures reliable skill triggering: the description
catches semantic matching, while the CLAUDE.md directive provides an
authoritative instruction that Claude cannot deprioritize in favor of
raw tool access.
The `claude mcp add` command fails with "already exists" when the server
is already registered. Additionally, configs written by setup/update used
a bare package name without @latest, causing npx to serve stale cached
versions indefinitely.
🔧 CLI registration:
- Remove existing entry before re-adding for Claude Code (both setup and update flows)
- Silently ignore removal errors when entry doesn't exist yet
⚡ Auto-update via @latest:
- Write @latest suffix in JSON configs, CLI commands, and manual instructions
- Smart detection in update flow: skip if config already has @latest,
offer migration if pinned, offer creation if missing
🎯 Users who run setup or update now get configs that always fetch the
newest version on MCP client restart, eliminating the stale-cache problem
without requiring manual npm cache clearing.
