feat: add minemap layout.

Author: PttCodingMan

CLAUDE.md

@@ -125,8 +125,12 @@ Docker Compose: backend (uvicorn, port 8000) + frontend (nginx, port 3000). Shar
 
 ## Development Workflow
 
-After completing any development task, always run the following before reporting the task as done:
+Standard loop for every task:
 
-1. **Tests** — run `make test` (or the relevant subset: `make test-backend` / `make test-frontend`) and make sure everything passes.
-2. **Lint** — run `make lint` for frontend changes.
-3. **Code review** — perform a self-review of the diff for non-trivial changes.
+1. **Develop** — implement the change.
+2. **Test** — `make test` (or relevant subset: `make test-backend` / `make test-frontend`). Must pass.
+3. **Code review** — self-review the diff. If issues found, return to step 1.
+
+Repeat until the review surfaces no further issues. Then report done.
+
+Frontend changes also require `make lint` before review.

backend/app/database.py

@@ -79,6 +79,7 @@
     version     INTEGER NOT NULL DEFAULT 1,
     is_public   INTEGER NOT NULL DEFAULT 0,
     page_type   TEXT NOT NULL DEFAULT 'document',
+    mindmap_layout TEXT,
     deleted_at  TIMESTAMP,
     created_by  INTEGER REFERENCES users(id),
     created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

backend/app/migrations.py

@@ -146,6 +146,17 @@ async def _m009_page_type(db: aiosqlite.Connection) -> None:
         )
 
 
+async def _m011_mindmap_layout(db: aiosqlite.Connection) -> None:
+    """Add `mindmap_layout` to pages so authors can pick LR / RL / Radial.
+
+    Nullable TEXT — NULL means "use the frontend default" (`'lr'`), so legacy
+    rows render unchanged. Validation is enforced by Pydantic Literal in
+    schemas.MindmapLayout, not at the DB layer (matches `page_type`).
+    """
+    if not await _column_exists(db, "pages", "mindmap_layout"):
+        await db.execute("ALTER TABLE pages ADD COLUMN mindmap_layout TEXT")
+
+
 async def _m010_site_settings(db: aiosqlite.Connection) -> None:
     """Create site_settings for branding overrides and the home-page slug.
 
@@ -175,6 +186,7 @@ async def _m010_site_settings(db: aiosqlite.Connection) -> None:
     (8, "api_tokens_extend", _m008_api_tokens_extend),
     (9, "page_type", _m009_page_type),
     (10, "site_settings", _m010_site_settings),
+    (11, "mindmap_layout", _m011_mindmap_layout),
 ]
 
 
@@ -271,6 +283,8 @@ async def _detect_preexisting(db: aiosqlite.Connection) -> set[int]:
     )
     if rows:
         applied.add(10)
+    if await _column_exists(db, "pages", "mindmap_layout"):
+        applied.add(11)
     return applied
 
 

backend/app/routers/pages.py

@@ -286,9 +286,9 @@ async def create_page(body: PageCreate, user=Depends(get_current_user)):
         candidate = await unique_slug(db, slugify(body.title, body.slug))
         try:
             cursor = await db.execute(
-                """INSERT INTO pages (slug, title, content_md, parent_id, sort_order, version, page_type, created_by)
-                   VALUES (?, ?, ?, ?, ?, 1, ?, ?)""",
-                (candidate, body.title, content, body.parent_id, body.sort_order, body.page_type, user["id"]),
+                """INSERT INTO pages (slug, title, content_md, parent_id, sort_order, version, page_type, mindmap_layout, created_by)
+                   VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?)""",
+                (candidate, body.title, content, body.parent_id, body.sort_order, body.page_type, body.mindmap_layout, user["id"]),
             )
             slug = candidate
             page_id = cursor.lastrowid
@@ -421,6 +421,15 @@ async def update_page(slug: str, body: PageUpdate, user=Depends(get_current_user
     is_public = body.is_public if body.is_public is not None else current_is_public
     current_page_type = current.get("page_type") or "document"
     page_type = body.page_type if body.page_type is not None else current_page_type
+    # mindmap_layout is `Optional[Literal[...]]` — explicit NULL is meaningful
+    # (revert to default), so distinguish "field not in payload" from
+    # "field set to None" via model_fields_set, like parent_id above.
+    current_mindmap_layout = current.get("mindmap_layout")
+    mindmap_layout = (
+        body.mindmap_layout
+        if "mindmap_layout" in body.model_fields_set
+        else current_mindmap_layout
+    )
 
     content_changed = body.content_md is not None and body.content_md != current["content_md"]
     title_changed = body.title is not None and body.title != current["title"]
@@ -436,8 +445,8 @@ async def update_page(slug: str, body: PageUpdate, user=Depends(get_current_user
 
     await db.execute(
         """UPDATE pages SET title = ?, content_md = ?, parent_id = ?, sort_order = ?,
-           is_public = ?, page_type = ?, version = ?, updated_at = CURRENT_TIMESTAMP WHERE slug = ?""",
-        (title, content, parent_id, sort_order, 1 if is_public else 0, page_type, new_version, slug),
+           is_public = ?, page_type = ?, mindmap_layout = ?, version = ?, updated_at = CURRENT_TIMESTAMP WHERE slug = ?""",
+        (title, content, parent_id, sort_order, 1 if is_public else 0, page_type, mindmap_layout, new_version, slug),
     )
 
     # Update search index

backend/app/routers/public.py

@@ -40,7 +40,7 @@ async def get_public_page(slug: str, request: Request):
 
     db = await get_db()
     rows = await db.execute_fetchall(
-        """SELECT p.slug, p.title, p.content_md, p.page_type, p.updated_at,
+        """SELECT p.slug, p.title, p.content_md, p.page_type, p.mindmap_layout, p.updated_at,
                   CASE WHEN u.display_name IS NOT NULL AND u.display_name != ''
                        THEN u.display_name ELSE u.username END AS author_name
            FROM pages p

backend/app/schemas.py

@@ -8,6 +8,10 @@
 # Add new types here (plus a frontend renderer) — no migration required.
 PageType = Literal["document", "mindmap"]
 
+# Mindmap layout strategy. Author-chosen, persisted on the page row. NULL is
+# treated as 'lr' by the frontend so existing rows render unchanged.
+MindmapLayout = Literal["lr", "rl", "radial"]
+
 
 # ── Auth ──
 class LoginRequest(BaseModel):
@@ -33,6 +37,7 @@ class PageCreate(BaseModel):
     template_id: Optional[int] = None
     slug: Optional[str] = None
     page_type: PageType = "document"
+    mindmap_layout: Optional[MindmapLayout] = None
 
 
 class PageUpdate(BaseModel):
@@ -42,6 +47,7 @@ class PageUpdate(BaseModel):
     sort_order: Optional[int] = None
     is_public: Optional[bool] = None
     page_type: Optional[PageType] = None
+    mindmap_layout: Optional[MindmapLayout] = None
     base_version: Optional[int] = None  # for optimistic locking
 
 
@@ -61,6 +67,7 @@ class PageResponse(BaseModel):
     version: int = 1
     is_public: bool = False
     page_type: PageType = "document"
+    mindmap_layout: Optional[MindmapLayout] = None
     created_by: Optional[int] = None
     author_name: Optional[str] = None
     created_at: Optional[str] = None
@@ -73,6 +80,7 @@ class PublicPageResponse(BaseModel):
     title: str
     content_md: str
     page_type: PageType = "document"
+    mindmap_layout: Optional[MindmapLayout] = None
     updated_at: Optional[str] = None
     author_name: Optional[str] = None
     diagrams: dict[str, str] = {}

backend/tests/test_mindmap_layout.py

@@ -0,0 +1,142 @@
+"""Backend coverage for the `pages.mindmap_layout` column.
+
+The frontend treats NULL as `'lr'`, so existing rows must keep returning
+`null` and the field must round-trip through both create and update without
+bumping `pages.version`.
+"""
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_create_mindmap_page_omits_layout_returns_null(auth_client):
+    response = await auth_client.post(
+        "/api/pages",
+        json={
+            "title": "ML Default",
+            "slug": "ml-default",
+            "page_type": "mindmap",
+            "content_md": "# Root",
+        },
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["page_type"] == "mindmap"
+    assert "mindmap_layout" in data
+    assert data["mindmap_layout"] is None
+
+
+@pytest.mark.asyncio
+async def test_create_with_explicit_layout_persists(auth_client):
+    response = await auth_client.post(
+        "/api/pages",
+        json={
+            "title": "ML Radial",
+            "slug": "ml-radial",
+            "page_type": "mindmap",
+            "mindmap_layout": "radial",
+            "content_md": "# Root",
+        },
+    )
+    assert response.status_code == 201
+    assert response.json()["mindmap_layout"] == "radial"
+
+    fetched = await auth_client.get("/api/pages/ml-radial")
+    assert fetched.status_code == 200
+    assert fetched.json()["mindmap_layout"] == "radial"
+
+
+@pytest.mark.asyncio
+async def test_update_layout_does_not_bump_version(auth_client):
+    create = await auth_client.post(
+        "/api/pages",
+        json={
+            "title": "ML Vbump",
+            "slug": "ml-vbump",
+            "page_type": "mindmap",
+            "content_md": "# Root",
+        },
+    )
+    assert create.status_code == 201
+    starting_version = create.json()["version"]
+
+    # Layout-only edit: must persist and must NOT bump the version counter
+    # (matches is_public / page_type behavior — see pages.py optimistic-lock
+    # logic: only content_md / title bump version).
+    res = await auth_client.put(
+        "/api/pages/ml-vbump",
+        json={"mindmap_layout": "rl"},
+    )
+    assert res.status_code == 200
+    body = res.json()
+    assert body["mindmap_layout"] == "rl"
+    assert body["version"] == starting_version
+
+
+@pytest.mark.asyncio
+async def test_update_layout_to_invalid_value_returns_422(auth_client):
+    await auth_client.post(
+        "/api/pages",
+        json={
+            "title": "ML Bad",
+            "slug": "ml-bad",
+            "page_type": "mindmap",
+            "content_md": "# Root",
+        },
+    )
+    res = await auth_client.put(
+        "/api/pages/ml-bad",
+        json={"mindmap_layout": "diagonal"},
+    )
+    assert res.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_update_layout_back_to_null(auth_client):
+    await auth_client.post(
+        "/api/pages",
+        json={
+            "title": "ML Reset",
+            "slug": "ml-reset",
+            "page_type": "mindmap",
+            "mindmap_layout": "radial",
+            "content_md": "# Root",
+        },
+    )
+    res = await auth_client.put(
+        "/api/pages/ml-reset",
+        json={"mindmap_layout": None},
+    )
+    assert res.status_code == 200
+    assert res.json()["mindmap_layout"] is None
+
+    fetched = await auth_client.get("/api/pages/ml-reset")
+    assert fetched.json()["mindmap_layout"] is None
+
+
+@pytest.mark.asyncio
+async def test_layout_allowed_on_document_page(auth_client):
+    """Layout column has no meaning for `page_type='document'`, but we accept
+    it anyway so toggling page_type doesn't lose the setting."""
+    res = await auth_client.post(
+        "/api/pages",
+        json={
+            "title": "Doc With Layout",
+            "slug": "doc-with-layout",
+            "page_type": "document",
+            "mindmap_layout": "radial",
+            "content_md": "Body",
+        },
+    )
+    assert res.status_code == 201
+    assert res.json()["mindmap_layout"] == "radial"
+
+
+@pytest.mark.asyncio
+async def test_get_response_always_includes_layout_key(auth_client):
+    await auth_client.post(
+        "/api/pages",
+        json={"title": "Plain Doc", "slug": "plain-doc", "content_md": "x"},
+    )
+    res = await auth_client.get("/api/pages/plain-doc")
+    assert res.status_code == 200
+    assert "mindmap_layout" in res.json()