documentation + semantic changes markdown and preview tabs

markrai · markrai · commit 33f3c055e621 · 2026-05-15T07:13:33.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,7 +6,7 @@
 
 ### Features
 
-- **Todo notes Markdown preview (Phase 1)** - When **`SCRUMBOY_MARKDOWN_NOTES_ENABLED=1`** (also accepts **`true`** / **`on`** / **`yes`**), the todo dialog Notes field gains **Write** / **Preview** tabs with a sanitized Markdown preview (headings, emphasis, lists, blockquotes, inline/fenced code, horizontal rules, and safe **`http`** / **`https`** links). Todo **Title** and board card titles stay plain text; notes still persist as the raw **`todos.body`** string with no schema changes.
+- **Todo notes Markdown preview (Phase 1)** - When **`SCRUMBOY_MARKDOWN_NOTES_ENABLED=1`** (also accepts **`true`** / **`on`** / **`yes`**), the todo dialog Notes field gains **markdown** / **preview** tabs with a sanitized Markdown preview (headings, emphasis, lists, blockquotes, inline/fenced code, horizontal rules, and safe **`http`** / **`https`** links). Todo **Title** and board card titles stay plain text; notes still persist as the raw **`todos.body`** string with no schema changes.
 
 - **Auth status flag** - **`/api/auth/status`** and bootstrap auth payloads expose **`markdownNotesEnabled`** so the UI only shows preview controls when the server has opted in.
 
@@ -21,7 +21,7 @@
 ### Tests
 
 - **Markdown preview** - Supported subset rendering, safe vs rejected link schemes, and neutralization of raw HTML, dangerous links, and image syntax.
-- **Todo dialog** - Write/Preview tab behavior gated on **`markdownNotesEnabled`**.
+- **Todo dialog** - markdown/preview tab behavior gated on **`markdownNotesEnabled`**.
 - **Server/config** - **`SCRUMBOY_MARKDOWN_NOTES_ENABLED`** parsing and **`markdownNotesEnabled`** on auth status responses.
 
 ## [3.15.4] - 2026-05-05
diff --git a/FAQ.md b/FAQ.md
@@ -0,0 +1,13 @@
+# FAQ
+
+## How do I enable Markdown in my notes?
+
+Set `SCRUMBOY_MARKDOWN_NOTES_ENABLED=1` on the server (also accepts `true`, `on`, or `yes`; case-insensitive). The feature defaults to off.
+
+After a restart, the todo dialog **Notes** field shows **markdown** and **preview** tabs. **markdown** is the source editor; **preview** is a sanitized rendered view. Supported syntax includes headings, emphasis, lists, blockquotes, inline and fenced code, horizontal rules (`---` on its own line with blank lines around it), and safe `http`/`https` links.
+
+Notes are still stored as raw markdown in `todos.body`. Todo titles and board card titles stay plain text. The server exposes `markdownNotesEnabled` on `/api/auth/status` so the UI only shows the tabs when the feature is enabled.
+
+Preview hardening: HTML in notes is not rendered; images stay as escaped text; dangerous link schemes and embedded content are stripped or neutralized.
+
+For architecture, security, and source references, see [`docs/markdown.md`](docs/markdown.md).
diff --git a/README.md b/README.md
@@ -193,6 +193,8 @@ Simplicity of a light Kanban, with the power of structured systems: Roles, sprin
 
 - Sticky-Note Wall - per-project scratchpad of draggable sticky notes on the board (see `docs/WALL.md`).
 
+- Todo notes Markdown preview - markdown/preview tabs in the todo Notes field (see `FAQ.md`, `docs/markdown.md`).
+
 ---
 
 ## Integrations & API Access
diff --git a/docs/markdown.md b/docs/markdown.md
@@ -0,0 +1,203 @@
+# Todo notes Markdown (Phase 1)
+
+Phase 1 adds an **optional, client-side preview** of Markdown in the todo dialog **Notes** field. The server stores and serves notes as **plain text**; it does not parse or sanitize Markdown. Enabling the feature only exposes UI and loads browser libraries—the preview pipeline runs entirely in the SPA.
+
+For operator setup, see [`FAQ.md`](../FAQ.md). This document describes architecture, configuration, and the preview security model.
+
+---
+
+## Scope
+
+| In scope | Out of scope |
+|----------|----------------|
+| **markdown** / **preview** tabs in the Edit/New Todo dialog (`#todoBody`, `#todoBodyPreview`) | Rendering Markdown on the board, dashboard, or notifications |
+| Preview of `todos.body` when the user opens the **preview** tab | Server-side Markdown → HTML conversion |
+| Sanitized HTML in the preview pane only | WYSIWYG editing (Notes stay a `<textarea>`) |
+| Raw Markdown persisted on create/patch | Images, raw HTML, or non-http(s) links in preview |
+
+Todo **titles** and card titles on the board are always escaped plain text (see `board-rendering` tests).
+
+---
+
+## Configuration
+
+| Variable | Default | Enabled when |
+|----------|---------|--------------|
+| `SCRUMBOY_MARKDOWN_NOTES_ENABLED` | off (unset) | `1`, `true`, `on`, or `yes` (trimmed, case-insensitive) |
+
+Parsed in `internal/config/config.go` (`markdownNotesEnabledFromEnv`), passed through `cmd/scrumboy/main.go` into the HTTP server (`ServerOpts.MarkdownNotesEnabled`), and exposed to the SPA as **`markdownNotesEnabled`** on:
+
+- `GET /api/auth/status` (authenticated and anonymous status payloads in `internal/httpapi/routing_auth.go`)
+
+The UI reads that flag once during auth bootstrap (`modules/router.ts` → `setMarkdownNotesEnabled`) and gates tab visibility in `modules/dialogs/todo.ts` (`markdownNotesPreviewEnabled()`).
+
+There is **no per-project** or per-user toggle; it is instance-wide.
+
+---
+
+## Data flow
+
+```
+User edits textarea (#todoBody)
+        │
+        ▼
+Create/Patch API ──► todos.body (raw Markdown string, unchanged)
+        │
+        ▼ (preview tab only, client-side)
+renderMarkdownPreviewInto()
+        │
+        ├─► markdown-it.render()  (html: false)
+        └─► DOMPurify + link policy + DOM cleanup
+                │
+                ▼
+        #todoBodyPreview innerHTML (ephemeral, not saved)
+```
+
+`modules/dialogs/todo-submit.ts` passes `body` through unchanged in create and patch payloads. Tests in `todo-submit.test.ts` assert Markdown is not converted to HTML before send.
+
+---
+
+## Frontend
+
+### DOM (`internal/httpapi/web/index.html`)
+
+- **Label row:** `Notes` label and `#todoBodyToggle` (tab list: `#todoBodyWriteTab`, `#todoBodyPreviewTab`).
+- **Editor:** `#todoBody` (textarea) and `#todoBodyPreview` (preview `div`) inside `.todo-notes-editor`.
+- Tabs are hidden when `markdownNotesEnabled` is false (`hidden` on `#todoBodyToggle`).
+
+### Todo dialog (`modules/dialogs/todo.ts`)
+
+- **`todoNotesMode`:** `"markdown"` | `"preview"`.
+- **`syncTodoNotesModeUI()`:** toggles `hidden` on textarea vs preview, `is-active` / `aria-pressed` on tabs.
+- **`renderTodoNotesPreview()`:** calls `renderMarkdownPreviewInto`; on vendor/render failure, shows a toast and falls back to markdown mode.
+- **`input` listener:** re-renders preview live while the preview tab is active.
+
+### Preview module (`modules/markdown-preview.ts`)
+
+Exported API:
+
+- `renderMarkdownToSafeHtml(markdown: string): string`
+- `renderMarkdownPreviewInto(container: HTMLElement, markdown: string): void`
+
+Empty or whitespace-only notes set `todo-markdown-preview--empty` and clear the container (placeholder via CSS `::before`).
+
+### Styles (`styles.css`)
+
+Preview typography and colors are scoped under `#todoDialog .todo-markdown-preview` (headings, lists, blockquote, code, `pre`, links, `hr`).
+
+### State
+
+- `current._markdownNotesEnabled` in `modules/state/state.ts`, set from auth status only (not from board payloads).
+
+---
+
+## Rendering pipeline
+
+### 1. markdown-it
+
+Loaded from `/vendor/markdown-it.min.js` (global `window.markdownit`). Pinned dependency: `markdown-it@14.1.1` in `internal/httpapi/web/package.json`, copied by `scripts/sync-vendor.mjs`.
+
+Instance options (`getMarkdownRenderer()`):
+
+| Option | Value | Rationale |
+|--------|-------|-----------|
+| `html` | `false` | Disables raw HTML blocks in source Markdown |
+| `breaks` | `true` | Single newlines become `<br>` |
+| `linkify` | `false` | Bare URLs are not auto-linked (explicit `[text](url)` only) |
+
+**Custom rule:** `renderer.rules.image` rewrites image tokens to **escaped plain text** (`![alt](url)`) so no `<img>` is emitted.
+
+### 2. DOMPurify
+
+Second pass via `/vendor/purify.min.js` (`dompurify@3.4.3`):
+
+- **`ALLOWED_TAGS`:** `a`, `blockquote`, `br`, `code`, `em`, `h1`–`h6`, `hr`, `li`, `ol`, `p`, `pre`, `strong`, `ul`
+- **`ALLOWED_ATTR`:** `href`, `rel`, `target` only
+- ARIA and `data-*` attributes disallowed
+
+### 3. Post-sanitize DOM pass
+
+On a detached `<template>`:
+
+1. Remove any `img`, `iframe`, `object`, `embed`, `script`, `svg` that survived parsing.
+2. For each `<a>`:
+   - **`isSafeLinkHref`:** allow empty-scheme-relative paths (`/`, `./`, `../`, `#`, `?`); allow `http`/`https` only for explicit schemes; reject `//`, `javascript:`, `data:`, `mailto:`, `tel:`, etc.
+   - **External** (`http://` / `https://`): set `target="_blank"` and `rel="noopener noreferrer"`.
+   - **Unsafe href:** replace anchor with text node (link text only).
+
+---
+
+## Supported Markdown (preview)
+
+Verified in `modules/markdown-preview.test.ts`:
+
+- ATX headings `#` … `######`
+- `**bold**`, `*italic*`
+- Bullet and ordered lists
+- Blockquotes (`>`)
+- Inline `` `code` `` and fenced code blocks
+- Thematic breaks (`---`, `***`, `___`) on their own line (CommonMark rules; blank lines often required)
+- `[label](https://…)` and safe same-origin relative links
+
+**Not rendered as HTML in preview:**
+
+- `![alt](url)` → escaped literal
+- Raw HTML in source → escaped in output
+- Dangerous or non-web link schemes → plain text
+- Protocol-relative URLs (`//host/...`)
+
+---
+
+## Security notes
+
+- **XSS surface** is limited to the preview `div` in the todo dialog; content is never written back to the server as HTML.
+- **CSP / trust:** preview depends on vendored `markdown-it` and DOMPurify; `npm test` in `internal/httpapi/web` runs `verify-vendor.mjs` before Vitest.
+- **Link exfiltration:** only `http`/`https` external navigation; `noopener noreferrer` on external tabs.
+- **No Markdown on titles** avoids XSS or layout surprises on shared boards and SSE-driven card updates.
+
+---
+
+## Build, vendor, and PWA
+
+| Asset | Role |
+|-------|------|
+| `/vendor/markdown-it.min.js` | Parser (eager script in `index.html`) |
+| `/vendor/purify.min.js` | Sanitizer (eager script in `index.html`) |
+| `/dist/markdown-preview.js` | Compiled module (TypeScript → `dist/`) |
+
+Service worker (`sw.js`) precaches vendor scripts and `dist/markdown-preview.js` for offline-capable loads after first visit.
+
+Regenerate vendor files after dependency bumps:
+
+```bash
+cd internal/httpapi/web
+npm run sync:vendor
+npm run verify:vendor
+```
+
+---
+
+## Tests
+
+| Location | Covers |
+|----------|--------|
+| `internal/config/config_markdown_enabled_test.go` | Env parsing |
+| `internal/httpapi/routing_auth_markdown_test.go` | `markdownNotesEnabled` on auth status |
+| `modules/markdown-preview.test.ts` | Supported subset, links, HTML/images neutralization |
+| `modules/dialogs/todo-markdown-preview.test.ts` | Dialog gating, preview vs textarea, raw body on save |
+| `modules/dialogs/todo-submit.test.ts` | API payloads keep raw Markdown |
+| `modules/views/board-rendering.test.ts` | Card titles do not render note Markdown |
+
+---
+
+## Key source files
+
+| Area | Path |
+|------|------|
+| Env / config | `internal/config/config.go` |
+| Server flag | `internal/httpapi/server.go`, `cmd/scrumboy/main.go` |
+| Auth JSON | `internal/httpapi/routing_auth.go` |
+| Preview core | `internal/httpapi/web/modules/markdown-preview.ts` |
+| Todo UI | `internal/httpapi/web/modules/dialogs/todo.ts` |
+| Markup | `internal/httpapi/web/index.html` |
+| Vendor sync | `internal/httpapi/web/scripts/sync-vendor.mjs` |
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
@@ -46,7 +46,7 @@ type Options struct {
 	// set SCRUMBOY_WALL_ENABLED=0 to disable (see config.FromEnv semantics).
 	WallEnabled bool
 
-	// MarkdownNotesEnabled gates the todo notes write/preview experience in the
+	// MarkdownNotesEnabled gates the todo notes markdown/preview experience in the
 	// SPA. When false, the frontend behaves exactly as before.
 	MarkdownNotesEnabled bool
 }
diff --git a/internal/httpapi/web/dist/dialogs/todo.js b/internal/httpapi/web/dist/dialogs/todo.js
@@ -10,7 +10,7 @@ import { computeTodoDialogPermissions, setTodoFormPermissions, } from './todo-pe
 import { renderTagsChips, resetTodoTagAutocompleteBindings, setupTagAutocomplete, } from './todo-tags.js';
 export { getTodoFormPermissions, } from './todo-permissions.js';
 export { getTagsFromChips, normalizeTagName, removeTag, renderTagAutocomplete, renderTagsChips, setupTagAutocomplete, } from './todo-tags.js';
-let todoNotesMode = "write";
+let todoNotesMode = "markdown";
 let todoNotesPreviewBound = false;
 export function resolveColumnKey(raw) {
     const v = (raw || "").trim();
@@ -84,7 +84,7 @@ function renderTodoNotesPreview() {
     }
     catch (err) {
         showToast(err?.message || "Markdown preview is unavailable");
-        todoNotesMode = "write";
+        todoNotesMode = "markdown";
         syncTodoNotesModeUI();
     }
 }
@@ -94,7 +94,7 @@ function syncTodoNotesModeUI() {
         todoBodyToggle.hidden = !previewEnabled;
     }
     if (!previewEnabled) {
-        todoNotesMode = "write";
+        todoNotesMode = "markdown";
     }
     const isPreview = previewEnabled && todoNotesMode === "preview";
     if (todoBody) {
@@ -128,7 +128,7 @@ function bindTodoNotesPreviewControls() {
     todoNotesPreviewBound = true;
     if (todoBodyWriteTab) {
         todoBodyWriteTab.addEventListener("click", () => {
-            setTodoNotesMode("write");
+            setTodoNotesMode("markdown");
         });
     }
     if (todoBodyPreviewTab) {
@@ -378,7 +378,7 @@ export async function openTodoDialog(opts) {
             shareTodoBtn.style.display = "";
         setDates(todo.createdAt, todo.updatedAt);
     }
-    setTodoNotesMode("write");
+    setTodoNotesMode("markdown");
     const tagInputEl = document.getElementById("todoTags");
     if (tagInputEl) {
         tagInputEl.replaceWith(tagInputEl.cloneNode(true));
diff --git a/internal/httpapi/web/index.html b/internal/httpapi/web/index.html
@@ -131,8 +131,8 @@
           <div class="field__label-row">
             <label class="field__label" for="todoBody">Notes</label>
             <div class="todo-notes-tabs" id="todoBodyToggle" hidden role="tablist" aria-label="Notes editor mode">
-              <button class="todo-notes-tab is-active" type="button" id="todoBodyWriteTab" role="tab" aria-pressed="true">write</button>
-              <button class="todo-notes-tab" type="button" id="todoBodyPreviewTab" role="tab" aria-pressed="false">markdown</button>
+              <button class="todo-notes-tab is-active" type="button" id="todoBodyWriteTab" role="tab" aria-pressed="true">markdown</button>
+              <button class="todo-notes-tab" type="button" id="todoBodyPreviewTab" role="tab" aria-pressed="false">preview</button>
             </div>
           </div>
           <div class="todo-notes-editor">
diff --git a/internal/httpapi/web/modules/dialogs/todo-markdown-preview.test.ts b/internal/httpapi/web/modules/dialogs/todo-markdown-preview.test.ts
@@ -145,7 +145,7 @@ describe("todo markdown preview", () => {
     expect((document.getElementById("todoBodyPreview") as HTMLElement).hidden).toBe(true);
   });
 
-  it("shows the write/preview toggle and empty preview state when enabled", async () => {
+  it("shows the markdown/preview toggle and empty preview state when enabled", async () => {
     mockTodoModule(true);
     const { openTodoDialog } = await import("./todo.js");
 
@@ -184,7 +184,7 @@ describe("todo markdown preview", () => {
     const title = document.getElementById("todoTitle") as HTMLInputElement;
     const body = document.getElementById("todoBody") as HTMLTextAreaElement;
     const previewTab = document.getElementById("todoBodyPreviewTab") as HTMLButtonElement;
-    const writeTab = document.getElementById("todoBodyWriteTab") as HTMLButtonElement;
+    const markdownTab = document.getElementById("todoBodyWriteTab") as HTMLButtonElement;
     const preview = document.getElementById("todoBodyPreview") as HTMLElement;
 
     expect(title.value).toBe(rawTitle);
@@ -195,7 +195,7 @@ describe("todo markdown preview", () => {
     expect(preview.innerHTML).toContain("<h1>Heading</h1>");
     expect(preview.innerHTML).toContain("<strong>bold</strong>");
 
-    writeTab.click();
+    markdownTab.click();
     expect(body.hidden).toBe(false);
     expect(body.value).toBe(rawBody);
   });
diff --git a/internal/httpapi/web/modules/dialogs/todo.ts b/internal/httpapi/web/modules/dialogs/todo.ts
@@ -51,9 +51,9 @@ export {
   setupTagAutocomplete,
 } from './todo-tags.js';
 
-type TodoNotesMode = "write" | "preview";
+type TodoNotesMode = "markdown" | "preview";
 
-let todoNotesMode: TodoNotesMode = "write";
+let todoNotesMode: TodoNotesMode = "markdown";
 let todoNotesPreviewBound = false;
 
 export function resolveColumnKey(raw: string | undefined | null): string {
@@ -138,7 +138,7 @@ function renderTodoNotesPreview(): void {
     );
   } catch (err: any) {
     showToast(err?.message || "Markdown preview is unavailable");
-    todoNotesMode = "write";
+    todoNotesMode = "markdown";
     syncTodoNotesModeUI();
   }
 }
@@ -149,7 +149,7 @@ function syncTodoNotesModeUI(): void {
     (todoBodyToggle as HTMLElement).hidden = !previewEnabled;
   }
   if (!previewEnabled) {
-    todoNotesMode = "write";
+    todoNotesMode = "markdown";
   }
 
   const isPreview = previewEnabled && todoNotesMode === "preview";
@@ -187,7 +187,7 @@ function bindTodoNotesPreviewControls(): void {
 
   if (todoBodyWriteTab) {
     (todoBodyWriteTab as HTMLButtonElement).addEventListener("click", () => {
-      setTodoNotesMode("write");
+      setTodoNotesMode("markdown");
     });
   }
   if (todoBodyPreviewTab) {
@@ -441,7 +441,7 @@ export async function openTodoDialog(opts: {
     if (shareTodoBtn) (shareTodoBtn as HTMLElement).style.display = "";
     setDates(todo.createdAt, todo.updatedAt);
   }
-  setTodoNotesMode("write");
+  setTodoNotesMode("markdown");
 
   const tagInputEl = document.getElementById("todoTags") as HTMLInputElement | null;
   if (tagInputEl) {

Original file line number	Diff line number	Diff line change
`@@ -46,7 +46,7 @@ type Options struct {`
`46`	`46`	`// set SCRUMBOY_WALL_ENABLED=0 to disable (see config.FromEnv semantics).`
`47`	`47`	`WallEnabled bool`
`48`	`48`
`49`		`- // MarkdownNotesEnabled gates the todo notes write/preview experience in the`
	`49`	`+ // MarkdownNotesEnabled gates the todo notes markdown/preview experience in the`
`50`	`50`	`// SPA. When false, the frontend behaves exactly as before.`
`51`	`51`	`MarkdownNotesEnabled bool`
`52`	`52`	`}`