@@ -0,0 +1,71 @@
+"""JSON Canvas 1.0 validation; retain extension fields for lossless round trips."""
+import json
+import math
+import re
+
+
+def validate_canvas(content: str) -> str:
+    try:
+        value = json.loads(content)
+    except (ValueError, TypeError) as exc:
+        raise ValueError("Canvas content must be valid JSON") from exc
+    if not isinstance(value, dict):
+        raise ValueError("Canvas must be a JSON object")
+    nodes, edges = value.get("nodes", []), value.get("edges", [])
+    if not isinstance(nodes, list) or not isinstance(edges, list):
+        raise ValueError("Canvas nodes and edges must be arrays")
+    ids = set()
+
+    def text(item, key, required=False):
+        if required or key in item:
+            if not isinstance(item.get(key), str):
+                raise ValueError(f"Canvas {key} must be a string")
+
+    def identity(item):
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str) or not item["id"]:
+            raise ValueError("Canvas elements require a nonempty string id")
+        if item["id"] in ids:
+            raise ValueError("Canvas element ids must be unique")
+        ids.add(item["id"])
+        if "color" in item and (not isinstance(item["color"], str) or not re.fullmatch(r"[1-6]|#[0-9a-fA-F]{6}", item["color"])):
+            raise ValueError("Canvas color must be a preset 1–6 or #RRGGBB")
+
+    for node in nodes:
+        identity(node)
+        if node.get("type") not in ("text", "file", "link", "group"):
+            raise ValueError("Unknown canvas node type")
+        for key in ("x", "y", "width", "height"):
+            number = node.get(key)
+            if isinstance(number, bool) or not isinstance(number, (int, float)) or not math.isfinite(number) or number != int(number):
+                raise ValueError(f"Canvas {key} must be a finite integer")
+            if key in ("width", "height") and number <= 0:
+                raise ValueError("Canvas dimensions must be positive")
+        if node["type"] == "text":
+            text(node, "text", True)
+        elif node["type"] == "file":
+            text(node, "file", True)
+            text(node, "subpath")
+            if "subpath" in node and not node["subpath"].startswith("#"):
+                raise ValueError("Canvas subpath must start with #")
+        elif node["type"] == "link":
+            text(node, "url", True)
+        else:
+            text(node, "label")
+            text(node, "background")
+            if "backgroundStyle" in node and node["backgroundStyle"] not in ("cover", "ratio", "repeat"):
+                raise ValueError("Invalid canvas background style")
+    node_ids = set(ids)
+    for edge in edges:
+        identity(edge)
+        for key in ("fromNode", "toNode"):
+            text(edge, key, True)
+            if edge[key] not in node_ids:
+                raise ValueError("Canvas edges must reference existing nodes")
+        for key in ("fromSide", "toSide"):
+            if key in edge and edge[key] not in ("top", "right", "bottom", "left"):
+                raise ValueError("Invalid canvas connection side")
+        for key in ("fromEnd", "toEnd"):
+            if key in edge and edge[key] not in ("none", "arrow"):
+                raise ValueError("Invalid canvas connection endpoint")
+        text(edge, "label")
+    return content
@@ -1,4 +1,6 @@
-from typing import Optional
+from typing import Literal, Optional
+from pydantic import model_validator
+from .canvas import validate_canvas
 from .base import CamelModel
 
 
@@ -12,7 +14,7 @@ class Note(CamelModel):
     experiment_id: Optional[str] = None
     name: str
     parent_id: Optional[str] = None
-    type: str = "file"  # file | folder
+    type: str = "file"  # file | folder | canvas
     content: str = ""
     is_pinned: bool = False
     created_at: str
@@ -22,9 +24,17 @@ class Note(CamelModel):
 class NoteCreate(CamelModel):
     name: str
     parent_id: Optional[str] = None
-    type: str = "file"
+    type: Literal["file", "folder", "canvas"] = "file"
     content: str = ""
 
+    @model_validator(mode="after")
+    def validate_document(self):
+        if self.type == "canvas":
+            self.content = validate_canvas(self.content or '{"nodes":[],"edges":[]}')
+            if not self.name.lower().endswith(".canvas"):
+                self.name += ".canvas"
+        return self
+
 
 class NoteUpdate(CamelModel):
     name: Optional[str] = None
 
@@ -10,6 +10,8 @@
 from services.cost_service import record_openai_usage
 
 from models.note import Note, NoteCreate, NoteUpdate
+from models.canvas import validate_canvas
+from fastapi import HTTPException
 from models.note_batch import ItemNotes, NoteBatchRequest
 from services.db import get_client
 
@@ -124,6 +126,14 @@ def update_note(note_id: str, data: NoteUpdate) -> Optional[Note]:
         return None
     # exclude_unset (not exclude_none) so callers can explicitly set fields to null
     updates = data.model_dump(exclude_unset=True)
+    if existing.type == "canvas":
+        if "content" in updates:
+            try:
+                validate_canvas(updates["content"])
+            except ValueError as exc:
+                raise HTTPException(status_code=422, detail=str(exc)) from exc
+        if updates.get("name") and not updates["name"].lower().endswith(".canvas"):
+            updates["name"] += ".canvas"
     # When reassigning to a different source, null out all other source fields so
     # a note always belongs to exactly one source at a time.
     if any(f in updates for f in _SOURCE_FIELDS):
 
@@ -0,0 +1,71 @@
+import json
+from unittest.mock import Mock
+
+import pytest
+from pydantic import ValidationError
+
+from models.canvas import validate_canvas
+from models.note import Note, NoteCreate, NoteUpdate
+from services import note_service
+
+
+def node(**updates):
+    return {"id": "n1", "type": "text", "x": 0, "y": 0, "width": 300, "height": 200, "text": "Hello", **updates}
+
+
+def test_canvas_creation_defaults_and_extensions():
+    data = NoteCreate(name="Map", type="canvas")
+    assert data.name == "Map.canvas"
+    assert json.loads(data.content) == {"nodes": [], "edges": []}
+    content = json.dumps({"nodes": [node(researchos={"custom": True})], "edges": [], "vendor": {"future": 1}})
+    assert NoteCreate(name="Map.canvas", type="canvas", content=content).content == content
+
+
+@pytest.mark.parametrize("value", [None, [], {"nodes": None}, {"nodes": [node(), node()]}, {"nodes": [node(width=0)]}, {"nodes": [node(x=True)]}, {"nodes": [node(x=0.5)]}, {"nodes": [node(color="red")]}, {"nodes": [node(type="file", file="a.md", subpath="heading")]}, {"nodes": [node()], "edges": [{"id": "e", "fromNode": "n1", "toNode": "missing"}]}])
+def test_invalid_canvas_is_rejected(value):
+    with pytest.raises(ValueError):
+        validate_canvas(json.dumps(value))
+
+
+def test_optional_arrays_and_all_node_types():
+    assert validate_canvas('{}') == '{}'
+    data = {"nodes": [node(), node(id="f", type="file", file="Nested.canvas", subpath="#Heading"), node(id="l", type="link", url="https://example.com"), node(id="g", type="group", label="Group", background="image.png", backgroundStyle="ratio")], "edges": [{"id": "edge", "fromNode": "f", "toNode": "l", "fromSide": "bottom", "toSide": "top", "fromEnd": "arrow", "toEnd": "none", "color": "#123456", "label": "reference"}]}
+    assert json.loads(validate_canvas(json.dumps(data))) == data
+
+
+def test_canvas_create_api_rejects_bad_json_before_write(client, monkeypatch):
+    create = Mock()
+    monkeypatch.setattr(note_service, 'create_note', create)
+    result = client.post('/api/libraries/lib/notes', json={"name": "Bad", "type": "canvas", "content": "invalid"})
+    assert result.status_code == 422
+    create.assert_not_called()
+
+
+def test_update_rejects_invalid_content_before_database_write(monkeypatch):
+    existing = Note(id="c", name="Map.canvas", type="canvas", content='{}', created_at="now", updated_at="now")
+    monkeypatch.setattr(note_service, "get_note", lambda _: existing)
+    db = Mock()
+    monkeypatch.setattr(note_service, "get_client", lambda: db)
+    from fastapi import HTTPException
+    with pytest.raises(HTTPException) as error:
+        note_service.update_note("c", NoteUpdate(content="<p>Accidental HTML overwrite</p>"))
+    assert error.value.status_code == 422
+    db.table.assert_not_called()
+
+
+@pytest.mark.parametrize('scope,identifier', [('paper_id', 'paper'), ('website_id', 'site'), ('github_repo_id', 'repo'), ('library_id', 'library'), ('project_id', 'project'), ('experiment_id', 'experiment')])
+def test_canvas_persists_in_every_notes_scope(monkeypatch, scope, identifier):
+    db = Mock()
+    monkeypatch.setattr(note_service, 'get_client', lambda: db)
+    created = note_service.create_note(NoteCreate(name='Map', type='canvas', parent_id='folder'), **{scope: identifier})
+    assert created.type == 'canvas'
+    assert getattr(created, scope) == identifier
+    saved = db.table.return_value.insert.call_args.args[0]
+    assert saved['parent_id'] == 'folder'
+    assert json.loads(saved['content']) == {'nodes': [], 'edges': []}
+
+
+def test_existing_note_html_is_unchanged():
+    assert NoteCreate(name='Note', content='<p>Hello</p>').content == '<p>Hello</p>'
+    with pytest.raises(ValidationError):
+        NoteCreate(name='Invalid', type='unknown')
@@ -2,6 +2,7 @@
 
 ## For Users
 
+- [Canvas documents](canvas.md) — Visual notes, nested canvases, file cards, and portable exports
 - [User Guide](user-guide.md) — Walkthrough: first papers to projects to AI features
 - [Costs & Privacy](costs-and-privacy.md) — What goes to OpenAI, cost estimates, data ownership
 - [FAQ & Troubleshooting](faq.md) — Common questions and fixes
 
@@ -1,6 +1,6 @@
 # Notes API
 
-Notes implement a file-tree system. Each note is either a `file` (with HTML content) or a `folder`. Notes belong to exactly one parent scope.
+Notes implement a file-tree system. Each entry is a `file` (with HTML content), a `canvas` (with JSON Canvas content), or a `folder`. Notes belong to exactly one parent scope.
 
 ---
 
@@ -90,12 +90,31 @@ Request body (`NoteCreate`):
 }
 ```
 
-- `type`: `"file"` or `"folder"`. Folders have empty `content`.
+- `type`: `"file"`, `"folder"`, or `"canvas"`. Folders have empty `content`.
 - `parentId`: ID of parent note (folder) for nested structure; `null` for root-level.
-- `content`: HTML string (tiptap editor output). Empty string for folders.
+- `content`: HTML string for files, a serialized JSON Canvas 1.0 object for canvases, or an empty string for folders.
 
 Returns the created Note at `201`.
 
+### Canvas documents
+
+The same creation endpoint works in every scope:
+
+```json
+{
+  "name": "Research map.canvas",
+  "parentId": null,
+  "type": "canvas",
+  "content": "{\"nodes\":[],\"edges\":[]}"
+}
+```
+
+Omitting canvas content initializes empty `nodes` and `edges` arrays. Creation and rename append `.canvas` if absent. Save using `PATCH /api/notes/{id}` with the serialized document in `content`. The type of an existing entry is not changed by PATCH.
+
+Canvas creation and content updates validate JSON Canvas node types, geometry, unique IDs, colors, file subpaths, and connection endpoints. Invalid content returns `422` before any database write. Unknown extension fields are retained. Existing HTML note behavior is unchanged. No database migration is needed: the existing `notes.type` and `notes.content` columns store the document.
+
+ResearchOS-created file nodes retain their portable `file` path and add `researchos.noteId` for stable references across renames and moves. Local attachments may include `researchos.mediaData` or `researchos.textContent`; group backgrounds may include `researchos.backgroundData`. These optional extensions do not alter the JSON Canvas schema. See [Canvas guide](../canvas.md) for exports and interoperability.
+
 ---
 
 ## Update Note
 
@@ -0,0 +1,63 @@
+# Canvas documents
+
+Use **New canvas** in a notes explorer, or right-click a folder and choose **New canvas**. Canvases appear alongside notes and folders in library, paper, website, repository, project, and experiment notes. Names end in `.canvas`; storage uses the existing notes API and database, with no migration or new service required.
+
+The editor stores [JSON Canvas 1.0](https://jsoncanvas.org/spec/1.0/), the open format used by [Obsidian Canvas](https://obsidian.md/help/plugins/canvas). It preserves node ordering, standard optional fields, and extension fields on import and export.
+
+## Cards and connections
+
+- **Text** adds a Markdown card. Double-click to edit. Text supports headings, lists, tasks, links, code, tables, and images. **Convert to note** creates a rich-text note and replaces the card with a reference.
+- **File / canvas** adds a note or another canvas. Pick a folder to add its files, or drag entries from the explorer. Referenced notes show live content. **Edit linked note** edits the original through the existing rich-text editor; **Open file** opens its tab; **Swap file** relinks the card. **Heading / block** accepts `#Heading` or `#^block-id`.
+- Nested canvases show previews, with a depth limit and circular-reference detection. Open the nested canvas to continue navigating. Missing or ambiguous file paths show an unavailable state and can be relinked.
+- **Media** imports images, audio, video, PDF, or text files; local files can also be dropped. Each attachment is limited to 15 MB. Imported `.canvas` attachments become canvas documents in the current notes folder. Remote media can be referenced by an imported file node's HTTP(S) URL.
+- **Web page** embeds an HTTP(S) page in a sandboxed frame. The inspector can change or copy its URL and reload it. Some sites block embedding; their external link remains available.
+- **Group** creates a visual container around selected cards, or an empty group. Moving a group carries its contained cards. Set its label, color, and image background, with cover, aspect-ratio, or repeat rendering.
+- Drag a side handle to another card to connect them. Dropping a new connection on empty space creates a text card. Connections support labels, colors, side selection, and arrows at either or both ends. Drag endpoints to reconnect; drop an existing endpoint on empty space to disconnect. **Follow start/end** navigates to either card.
+
+## Editing and navigation
+
+Drag a card's header or preview body to move it, and selected card borders to resize. Move groups by their headers. Text editors, links, and media controls retain their normal interactions. Drag blank space for a selection box, Shift-click for multiple selection, or use Ctrl/Command+A. Alt-drag leaves a duplicate at the original position. The inspector offers duplication, deletion, layer ordering, grouping, six alignments, row/column/grid layouts, spacing distribution, and horizontal/vertical justification.
+
+Use Space-drag or the middle mouse button to pan, wheel to scroll, Ctrl/Command-wheel or pinch to zoom, and the minimap to navigate. The controls include fit-all, fit-selection, 100% zoom, group navigation, and card text search. Settings expose grid snapping, object snapping, resize aspect ratio, minimap visibility, and read-only mode.
+
+| Shortcut | Action |
+| --- | --- |
+| Ctrl/Command+S | Save canvas |
+| Ctrl/Command+Z | Undo |
+| Ctrl/Command+Y or Ctrl/Command+Shift+Z | Redo |
+| Ctrl/Command+D | Duplicate selection |
+| Ctrl/Command+C / V | Copy/paste cards within the open canvas |
+| Delete / Backspace | Remove selection and its connections |
+| Arrow keys | Move selected cards |
+| Shift+arrow | Move farther |
+| Shift+1 / Shift+2 | Fit all / fit selection |
+| Escape | Finish text editing or clear selection |
+
+Undo history holds the last 100 canvas operations and resets when the editor closes. Read-only mode prevents document changes while retaining navigation and export.
+
+## Saving and references
+
+Changes autosave after a short debounce. Writes are serialized per document, and switching tabs flushes pending changes. The directory receives each draft immediately. Unsaved content is also backed up in browser storage when available; a failed save shows **Retry save**, and reopening a canvas recovers its draft. Browser storage limits can prevent large media drafts from being backed up; API saving still works. The application warns before leaving with a pending save.
+
+Internal references use the note ID as an optional `researchos.noteId` extension. Renaming or moving a referenced note keeps the reference intact. File paths refresh on export. Imported paths resolve within the current source first, then across loaded sources if unique. A deleted ID does not silently resolve to a different file with the same name. References resolve only within notes loaded by the current library/project/panel.
+
+Canvases participate in directory search, pinning, recent notes, graph links, and backlinks. In a rich-text note, use **Embed canvas** or type `![[Name.canvas]]` to insert a preview. Ordinary wiki links can also target canvases.
+
+## Import and export
+
+- **Import .canvas** validates and replaces the current canvas, asking before replacing a nonempty document. Undo restores the previous document. Invalid imports leave it untouched. The import limit is 60 MB.
+- **Download .canvas** downloads the JSON document, including ResearchOS extensions. Other JSON Canvas applications use its standard file paths and ignore extensions they do not understand.
+- **Canvas + files (.zip)** packages the canvas, referenced notes and nested canvases, and local attachments/backgrounds. It strips internal note IDs so paths can resolve in another application. Export stops with a clear error if distinct files would overwrite the same archive path. Remote URLs remain references.
+- **PNG** exports the full canvas at 1× or 2×, the current viewport, or a privacy image hiding text. Very large exports are capped at 64 megapixels; use the viewport or lower scale. Browser restrictions can prevent remote media or embedded pages from appearing in an image.
+
+Attachments are stored in optional ResearchOS extensions inside the canvas, rather than separate backend uploads. Use ZIP export when moving media to Obsidian; a standalone `.canvas` file cannot supply separate attachment files to applications that ignore those extensions. Importing an Obsidian canvas does not grant this web application access to its local vault: matching notes must already exist in ResearchOS, or be added/relinked. ZIP export is supported; ZIP/vault import is not.
+
+## Compatibility boundaries
+
+This is an implementation of the JSON Canvas format and the core visual Canvas workflow, not the Obsidian application runtime. Obsidian Bases (`.base` databases), community plugin behaviors, vault filesystem services, Obsidian-specific commands/branding, and exact mobile long-press menus are not implemented. Generic file nodes referencing those files are preserved. Browser/touch interaction uses the graph editor's gestures; desktop and touch menus are not identical to Obsidian's.
+
+Local SVG and HTML media are not executed. Web embeds run in sandboxed frames, HTML note previews are sanitized, and Markdown cards do not execute embedded HTML. Cyclic previews stop rather than recursively rendering forever.
+
+## Development checks
+
+From `frontend`, run `npm run test:run`, `npm run test:e2e -- canvas.spec.js`, and `npm run build`. The repository currently has a pre-existing KaTeX/Tiptap peer-version mismatch; dependency installation may require `npm install --legacy-peer-deps`. From `backend`, run `.venv/Scripts/python.exe -m pytest tests/test_canvas.py tests/test_note_batch.py tests/test_chat_and_notes_routes.py -q` on Windows.