From d4d388462d6a4595e636d986873ddfc8134265d3 Mon Sep 17 00:00:00 2001
From: Bakhomious Basta <bakhomioussvp@gmail.com>
Date: Fri, 30 Oct 2026 03:14:40 +0100
Subject: [PATCH 1/2] feat(notes): save a note from its editor

Save, or Cmd/Ctrl+S, sends the editor's text with PUT and If-Match
naming the version the page loaded, the note's ETag. A 204 shows the
saved note at once and says so; a 412, from a note changed since it
loaded, keeps the editor and the text and says so; any other failure
keeps them and says the save failed. While the save runs, the editor
takes no typing and Save and Cancel wait.

Decision 402 now also records where Save sits, the status line, and
why the note renders before the PUT.
---
 apps/web/e2e/notes-edit.spec.ts          |  65 +++++++-
 apps/web/package.json                    |   1 +
 apps/web/pnpm-lock.yaml                  |   3 +
 apps/web/src/notes/NoteEditor.svelte     |  10 +-
 apps/web/src/notes/NotePage.save.test.ts |  88 +++++++++++
 apps/web/src/notes/NotePage.svelte       |  24 ++-
 apps/web/src/notes/api.test.ts           |  57 ++++++-
 apps/web/src/notes/api.ts                |  35 ++++-
 apps/web/src/notes/editor.test.ts        |  51 +++++-
 apps/web/src/notes/editor.ts             |  36 ++++-
 apps/web/src/notes/labels.test.ts        |  13 +-
 apps/web/src/notes/labels.ts             |  17 ++
 apps/web/src/notes/shown.svelte.ts       |  90 +++++++++--
 apps/web/src/notes/shown.test.ts         | 190 +++++++++++++++++++++++
 docs/plan.md                             |   2 +-
 15 files changed, 645 insertions(+), 37 deletions(-)
 create mode 100644 apps/web/src/notes/NotePage.save.test.ts
 create mode 100644 apps/web/src/notes/shown.test.ts

diff --git a/apps/web/e2e/notes-edit.spec.ts b/apps/web/e2e/notes-edit.spec.ts
index 104209b..db97332 100644
--- a/apps/web/e2e/notes-edit.spec.ts
+++ b/apps/web/e2e/notes-edit.spec.ts
@@ -1,3 +1,5 @@
+import type { Page, Request } from '@playwright/test';
+
 import { home } from './demo';
 import { expect, test } from './fixtures';
 
@@ -7,7 +9,7 @@ const riff = '---\ntags: [guitar]\n---\n# Riff\n\nPlay it **slow**.\n';
 test.beforeEach(async ({ page }) => {
   await page.route('/api/home', (route) => route.fulfill({ json: home }));
   await page.route('/api/notes/files/Songs/Riff.md', (route) =>
-    route.fulfill({ body: riff, contentType: 'text/markdown; charset=utf-8' })
+    route.fulfill({ body: riff, contentType: 'text/markdown; charset=utf-8', headers: { ETag: '"1"' } })
   );
 });
 
@@ -45,3 +47,64 @@ test('a note offers no Edit while the notes service saves no note', async ({ pag
   await expect(page.getByRole('article')).toContainText('Play it slow.');
   await expect(page.getByRole('button', { name: 'Edit' })).toHaveCount(0);
 });
+
+// Answers the note's saves with status, and keeps their requests.
+async function saves(page: Page, status: number): Promise<Request[]> {
+  const requests: Request[] = [];
+  await page.route('/api/notes/files/Songs/Riff.md', (route) => {
+    if (route.request().method() !== 'PUT') {
+      return route.fallback();
+    }
+    requests.push(route.request());
+    return route.fulfill({ status, headers: status === 204 ? { ETag: '"2"' } : {} });
+  });
+  return requests;
+}
+
+// The note's page from a notes service that saves notes, with the note in the editor and " Then fast." typed in it.
+async function typed(page: Page) {
+  await page.route('/api/notes', (route) => route.fulfill({ json: { files, editable: true } }));
+  await page.goto('/notes/Songs/Riff');
+  await page.getByRole('button', { name: 'Edit' }).click();
+  const line = page.getByRole('textbox', { name: 'Markdown' }).locator('.cm-line').nth(5);
+  await line.click();
+  await page.keyboard.press('End');
+  await page.keyboard.type(' Then fast.');
+  return line;
+}
+
+test('Save sends the note with the version it loaded, then shows the note and says it saved', async ({ page }) => {
+  const requests = await saves(page, 204);
+  await typed(page);
+
+  await page.getByRole('button', { name: 'Save' }).click();
+
+  await expect(page.getByRole('article')).toContainText('Play it slow. Then fast.');
+  await expect(page.getByText('Saved', { exact: true })).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Edit' })).toBeFocused();
+  expect(requests).toHaveLength(1);
+  expect(requests[0]?.headers()).toMatchObject({ 'if-match': '"1"', 'content-type': 'text/markdown; charset=utf-8' });
+  expect(requests[0]?.postData()).toBe(riff.replace('**slow**.', '**slow**. Then fast.'));
+});
+
+test('a note changed since it loaded keeps the editor and the text, and says so', async ({ page }) => {
+  await saves(page, 412);
+  const line = await typed(page);
+
+  await page.getByRole('button', { name: 'Save' }).click();
+
+  await expect(page.getByText('Not saved: the note has changed since it loaded')).toBeVisible();
+  await expect(line).toHaveText('Play it **slow**. Then fast.');
+  await expect(page.getByRole('article')).toHaveCount(0);
+});
+
+test('⌘S, or Ctrl+S, in the editor saves', async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === 'phone', 'a phone has no ⌘ or Ctrl key without a keyboard');
+  const requests = await saves(page, 204);
+  await typed(page);
+
+  await page.keyboard.press('ControlOrMeta+s');
+
+  await expect(page.getByText('Saved', { exact: true })).toBeVisible();
+  expect(requests).toHaveLength(1);
+});
diff --git a/apps/web/package.json b/apps/web/package.json
index 79c4303..dbae8f8 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -17,6 +17,7 @@
     "@codemirror/lang-markdown": "6.5.2",
     "@codemirror/lang-yaml": "6.1.3",
     "@codemirror/language": "6.13.1",
+    "@codemirror/state": "6.7.6",
     "@codemirror/view": "6.43.15",
     "@fontsource-variable/jetbrains-mono": "5.3.0",
     "@fontsource-variable/space-grotesk": "5.3.0",
diff --git a/apps/web/pnpm-lock.yaml b/apps/web/pnpm-lock.yaml
index 2994525..aef4aa3 100644
--- a/apps/web/pnpm-lock.yaml
+++ b/apps/web/pnpm-lock.yaml
@@ -24,6 +24,9 @@ importers:
       '@codemirror/language':
         specifier: 6.13.1
         version: 6.13.1
+      '@codemirror/state':
+        specifier: 6.7.6
+        version: 6.7.6
       '@codemirror/view':
         specifier: 6.43.15
         version: 6.43.15
diff --git a/apps/web/src/notes/NoteEditor.svelte b/apps/web/src/notes/NoteEditor.svelte
index 5130e48..ffaf890 100644
--- a/apps/web/src/notes/NoteEditor.svelte
+++ b/apps/web/src/notes/NoteEditor.svelte
@@ -1,12 +1,12 @@
 <script lang="ts">
-import { noteEditor } from './editor';
+import { type EditorPage, noteEditor } from './editor';
 
-// A note's Markdown in the editor, in place of the rendered note. A chunk of its own, with CodeMirror, which loads the
-// first time Edit is pressed.
-let { markdown }: { markdown: string } = $props();
+// A note's Markdown in the editor, in place of the rendered note, and the page that takes its text and saves it. A
+// chunk of its own, with CodeMirror, which loads the first time Edit is pressed.
+let { markdown, page }: { markdown: string; page: EditorPage } = $props();
 </script>
 
-<div class="editor" {@attach noteEditor(markdown)}></div>
+<div class="editor" {@attach noteEditor(markdown, page)}></div>
 
 <style>
 /* CodeMirror's own elements, which Svelte can't scope: a form field's box (decision 112), as tall as the note, with
diff --git a/apps/web/src/notes/NotePage.save.test.ts b/apps/web/src/notes/NotePage.save.test.ts
new file mode 100644
index 0000000..1570021
--- /dev/null
+++ b/apps/web/src/notes/NotePage.save.test.ts
@@ -0,0 +1,88 @@
+import { flushSync } from 'svelte';
+import { EditorView } from '@codemirror/view';
+import { fireEvent, render, screen } from '@testing-library/svelte';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+import NotePage from './NotePage.svelte';
+import { NotesState } from './state.svelte';
+import { noteAt } from './tree';
+
+const toDo = noteAt('/notes/Daily/To%20do')!;
+const markdown = '# To do\n\n- [ ] Tune';
+const typedText = `${markdown} now`;
+
+let fetchMock: ReturnType<typeof vi.fn<typeof fetch>>;
+
+beforeEach(() => {
+  fetchMock = vi.fn<typeof fetch>().mockResolvedValueOnce(new Response(markdown, { headers: { ETag: '"1"' } }));
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// The note's page from a notes service that saves notes, with the note in the editor and " now" typed at its end.
+async function typed() {
+  const notes = new NotesState();
+  notes.files = ['Daily/To do.md'];
+  notes.editable = true;
+  render(NotePage, { props: { note: toDo, notes } });
+  await fireEvent.click(await screen.findByRole('button', { name: 'Edit' }));
+  const view = EditorView.findFromDOM(await screen.findByRole('textbox', { name: 'Markdown' }))!;
+  view.dispatch({ changes: { from: markdown.length, insert: ' now' }, userEvent: 'input.type' });
+  return { notes, view };
+}
+
+function button(name: string): HTMLElement {
+  return screen.getByRole('button', { name });
+}
+
+test('Save follows Cancel, and saves the typed text, then shows the note, says so and gives Edit the focus', async () => {
+  await typed();
+  expect(screen.getAllByRole('button').map((each) => each.textContent?.trim())).toEqual(['Cancel', 'Save']);
+  expect(screen.getByRole('status').textContent).toBe('');
+  fetchMock.mockResolvedValueOnce(new Response(null, { status: 204, headers: { ETag: '"2"' } }));
+
+  await fireEvent.click(button('Save'));
+
+  expect(await screen.findByRole('article')).toHaveTextContent('Tune now');
+  expect(fetchMock).toHaveBeenLastCalledWith(
+    '/api/notes/files/Daily/To%20do.md',
+    expect.objectContaining({ method: 'PUT', body: typedText })
+  );
+  expect(screen.getByRole('status')).toHaveTextContent('Saved');
+  expect(button('Edit')).toHaveFocus();
+  expect(screen.queryByRole('button', { name: 'Save' })).not.toBeInTheDocument();
+});
+
+test('says so while a save runs, when Save, Cancel and the editor wait, and when the note has changed', async () => {
+  const { view } = await typed();
+  const put = Promise.withResolvers<Response>();
+  fetchMock.mockReturnValueOnce(put.promise);
+
+  await fireEvent.click(button('Save'));
+
+  expect(screen.getByRole('status')).toHaveTextContent('Saving…');
+  expect(button('Save')).toHaveAttribute('aria-disabled', 'true');
+  expect(button('Cancel')).toHaveAttribute('aria-disabled', 'true');
+  view.dispatch({ changes: { from: 0, insert: 'Late. ' }, userEvent: 'input.type' });
+  expect(view.state.doc.toString()).toBe(typedText);
+  put.resolve(new Response(null, { status: 412 }));
+  expect(await screen.findByText('Not saved: the note has changed since it loaded')).toBeInTheDocument();
+  expect(button('Save')).toHaveAttribute('aria-disabled', 'false');
+  expect(view.state.doc.toString()).toBe(typedText);
+});
+
+test('keeps Save and Cancel while the editor is open, when a sync says that notes no longer saves', async () => {
+  const { notes } = await typed();
+
+  flushSync(() => {
+    notes.editable = false;
+  });
+  expect(button('Save')).toBeInTheDocument();
+  await fireEvent.click(button('Cancel'));
+
+  expect(await screen.findByRole('article')).toHaveTextContent('Tune');
+  expect(screen.queryByRole('button')).not.toBeInTheDocument();
+});
diff --git a/apps/web/src/notes/NotePage.svelte b/apps/web/src/notes/NotePage.svelte
index ad493b2..4e190e6 100644
--- a/apps/web/src/notes/NotePage.svelte
+++ b/apps/web/src/notes/NotePage.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
 import PageHead from '../shell/PageHead.svelte';
+import { saveLabel } from './labels';
 import NoteBody from './NoteBody.svelte';
 import { ShownNote } from './shown.svelte';
 import type { NotesState } from './state.svelte';
@@ -21,16 +22,33 @@ $effect(() => {
   <PageHead eyebrow={note.folder}>{note.title}</PageHead>
   <div class="content">
     {#if shown.body.kind === 'loaded'}
-      {#if notes.editable}
+      <!-- The buttons stay while the editor is open, even if a sync says that notes no longer saves. -->
+      {#if notes.editable || shown.editing}
+        <!--
+          Save follows Cancel, so Cancel takes Edit's place, and Shift-Tab from the editor, which comes after them,
+          reaches Save first. aria-disabled, not disabled, so the focus stays on a button while its save runs.
+        -->
         <div class="tools form-row">
-          <button class="form-button" type="button" onclick={(event) => shown.toggle(event.currentTarget)}>
+          <button
+            class="form-button"
+            type="button"
+            aria-disabled={shown.busy}
+            onclick={() => shown.toggle()}
+            {@attach shown.button}
+          >
             {shown.editing ? 'Cancel' : 'Edit'}
           </button>
+          {#if shown.editing}
+            <button class="form-button" type="button" aria-disabled={shown.busy} onclick={() => void shown.save()}>
+              Save
+            </button>
+          {/if}
+          <p class="form-status" role="status">{saveLabel(shown.status)}</p>
         </div>
       {/if}
       {#if shown.editing}
         {#await import('./NoteEditor.svelte') then { default: NoteEditor }}
-          <NoteEditor markdown={shown.body.markdown} />
+          <NoteEditor markdown={shown.body.markdown} page={shown} />
         {:catch}
           <p class="failed">Couldn't load the editor.</p>
         {/await}
diff --git a/apps/web/src/notes/api.test.ts b/apps/web/src/notes/api.test.ts
index b161447..2ac1800 100644
--- a/apps/web/src/notes/api.test.ts
+++ b/apps/web/src/notes/api.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, expect, test, vi } from 'vitest';
 
-import { fetchNote, fetchNotes, fileUrl, syncNotes } from './api';
+import { fetchNote, fetchNotes, fileUrl, saveNote, syncNotes } from './api';
 
 afterEach(() => {
   vi.unstubAllGlobals();
@@ -49,14 +49,22 @@ test('gives a file’s URL, each name in its path escaped', () => {
   expect(fileUrl('My art/a b%?.png')).toBe('/api/notes/files/My%20art/a%20b%25%3F.png');
 });
 
-test('loads a note through the gateway, each name in its path escaped', async () => {
-  const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(new Response('# To do\n'));
+const version = '"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"';
+
+test('loads a note and its version through the gateway, each name in its path escaped', async () => {
+  const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(new Response('# To do\n', { headers: { ETag: version } }));
   vi.stubGlobal('fetch', fetchMock);
 
-  await expect(fetchNote('Daily/To do #1?.md')).resolves.toBe('# To do\n');
+  await expect(fetchNote('Daily/To do #1?.md')).resolves.toEqual({ markdown: '# To do\n', version });
   expect(fetchMock).toHaveBeenCalledExactlyOnceWith('/api/notes/files/Daily/To%20do%20%231%3F.md');
 });
 
+test('gives a blank version for a note answered without one', async () => {
+  vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response('# To do\n')));
+
+  await expect(fetchNote('Daily/To do.md')).resolves.toEqual({ markdown: '# To do\n', version: '' });
+});
+
 test('gives no note when the vault has none at the path', async () => {
   vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response('no such file', { status: 404 })));
 
@@ -74,3 +82,44 @@ test('fails to load a note when the gateway can not be reached', async () => {
 
   await expect(fetchNote('Daily/To do.md')).rejects.toThrow('Failed to fetch');
 });
+
+test('saves a note through the gateway, if it is still at the version it loaded, and gives its new version', async () => {
+  const saved = '"60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752"';
+  const fetchMock = vi
+    .fn<typeof fetch>()
+    .mockResolvedValue(new Response(null, { status: 204, headers: { ETag: saved } }));
+  vi.stubGlobal('fetch', fetchMock);
+
+  await expect(saveNote('Daily/To do #1?.md', '# To do\n\n- [ ] Tune\n', version)).resolves.toBe(saved);
+  expect(fetchMock).toHaveBeenCalledExactlyOnceWith('/api/notes/files/Daily/To%20do%20%231%3F.md', {
+    method: 'PUT',
+    headers: { 'Content-Type': 'text/markdown; charset=utf-8', 'If-Match': version },
+    body: '# To do\n\n- [ ] Tune\n',
+  });
+});
+
+test('gives a blank version for a save answered without one', async () => {
+  vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 204 })));
+
+  await expect(saveNote('Daily/To do.md', 'Tune', version)).resolves.toBe('');
+});
+
+test('gives no version when the note has changed since it loaded', async () => {
+  vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 412 })));
+
+  await expect(saveNote('Daily/To do.md', 'Tune', version)).resolves.toBeUndefined();
+});
+
+test.each([400, 428, 500, 502])('fails when the gateway answers a save with %i', async (status) => {
+  vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status })));
+
+  await expect(saveNote('Daily/To do.md', 'Tune', version)).rejects.toThrow(
+    `PUT /api/notes/files/Daily/To%20do.md: ${status}`
+  );
+});
+
+test('fails to save a note when the gateway can not be reached', async () => {
+  vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')));
+
+  await expect(saveNote('Daily/To do.md', 'Tune', version)).rejects.toThrow('Failed to fetch');
+});
diff --git a/apps/web/src/notes/api.ts b/apps/web/src/notes/api.ts
index 12da460..553b4c0 100644
--- a/apps/web/src/notes/api.ts
+++ b/apps/web/src/notes/api.ts
@@ -31,11 +31,18 @@ export function fileUrl(path: string): string {
   return `/api/notes/files/${path.split('/').map(encodeURIComponent).join('/')}`;
 }
 
+/** A note's Markdown, and its version, which a save sends back (decision 400). */
+export interface NoteFile {
+  markdown: string;
+  /** The note's ETag, the SHA-256 of its bytes in quotes; blank when the answer had none. */
+  version: string;
+}
+
 /**
- * Loads the note at path in the vault, such as "Work/Plans/Q3.md": its Markdown, or undefined when the vault has no
- * such note. Fails when the gateway can't be reached or answers with another error.
+ * Loads the note at path in the vault, such as "Work/Plans/Q3.md": its Markdown and version, or undefined when the
+ * vault has no such note. Fails when the gateway can't be reached or answers with another error.
  */
-export async function fetchNote(path: string): Promise<string | undefined> {
+export async function fetchNote(path: string): Promise<NoteFile | undefined> {
   const url = fileUrl(path);
   const response = await fetch(url);
   if (response.status === 404) {
@@ -44,5 +51,25 @@ export async function fetchNote(path: string): Promise<string | undefined> {
   if (!response.ok) {
     throw new Error(`GET ${url}: ${response.status}`);
   }
-  return response.text();
+  return { markdown: await response.text(), version: response.headers.get('ETag') ?? '' };
+}
+
+/**
+ * Saves markdown as the note at path, unless the note has changed since version: the saved note's version, or
+ * undefined when the note has changed. Fails when the gateway can't be reached or answers with another error.
+ */
+export async function saveNote(path: string, markdown: string, version: string): Promise<string | undefined> {
+  const url = fileUrl(path);
+  const response = await fetch(url, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'text/markdown; charset=utf-8', 'If-Match': version },
+    body: markdown,
+  });
+  if (response.status === 412) {
+    return undefined;
+  }
+  if (!response.ok) {
+    throw new Error(`PUT ${url}: ${response.status}`);
+  }
+  return response.headers.get('ETag') ?? '';
 }
diff --git a/apps/web/src/notes/editor.test.ts b/apps/web/src/notes/editor.test.ts
index bf96e93..6d07188 100644
--- a/apps/web/src/notes/editor.test.ts
+++ b/apps/web/src/notes/editor.test.ts
@@ -1,7 +1,7 @@
 import { EditorView } from '@codemirror/view';
-import { afterEach, expect, test } from 'vitest';
+import { afterEach, expect, test, vi } from 'vitest';
 
-import { noteEditor } from './editor';
+import { type EditorPage, noteEditor } from './editor';
 
 const markdown = ['---', 'tags: [guitar]', '---', '# To do', '', '- [ ] Tune'].join('\n');
 
@@ -9,11 +9,16 @@ afterEach(() => {
   document.body.replaceChildren();
 });
 
+// The editor's note page, which notes the text and the saves, with no save running.
+function notePage(): EditorPage {
+  return { edit: vi.fn(), save: vi.fn(), busy: false };
+}
+
 // An element on the page with the editor in it, and the attachment's cleanup.
-function attached(text: string) {
+function attached(text: string, page = notePage()) {
   const host = document.createElement('div');
   document.body.append(host);
-  const cleanup = noteEditor(text)(host);
+  const cleanup = noteEditor(text, page)(host);
   return { host, cleanup };
 }
 
@@ -88,3 +93,41 @@ test('goes with the element', () => {
 
   expect(host).toBeEmptyDOMElement();
 });
+
+test('tells the page its text after each change, and only then', () => {
+  const page = notePage();
+  const { host } = attached('Tune', page);
+  const view = EditorView.findFromDOM(host)!;
+
+  view.dispatch({ selection: { anchor: 2 } });
+  expect(page.edit).not.toHaveBeenCalled();
+  view.dispatch({ changes: { from: 4, insert: ' it' }, userEvent: 'input.type' });
+
+  expect(page.edit).toHaveBeenCalledExactlyOnceWith('Tune it');
+});
+
+// jsdom's platform isn't a Mac's, so CodeMirror takes Ctrl for the key, as it takes ⌘ on a Mac.
+test('Ctrl+S saves, and keeps the browser from saving the page', () => {
+  const page = notePage();
+  const { host } = attached('Tune', page);
+  const event = new KeyboardEvent('keydown', { key: 's', ctrlKey: true, bubbles: true, cancelable: true });
+
+  EditorView.findFromDOM(host)!.contentDOM.dispatchEvent(event);
+
+  expect(page.save).toHaveBeenCalledOnce();
+  expect(event.defaultPrevented).toBe(true);
+});
+
+test('takes no change while a save runs', () => {
+  const page = { ...notePage(), busy: true };
+  const { host } = attached('Tune', page);
+  const view = EditorView.findFromDOM(host)!;
+
+  view.dispatch({ changes: { from: 4, insert: ' it' }, userEvent: 'input.type' });
+  expect(view.state.doc.toString()).toBe('Tune');
+  expect(page.edit).not.toHaveBeenCalled();
+  page.busy = false;
+  view.dispatch({ changes: { from: 4, insert: ' it' }, userEvent: 'input.type' });
+
+  expect(view.state.doc.toString()).toBe('Tune it');
+});
diff --git a/apps/web/src/notes/editor.ts b/apps/web/src/notes/editor.ts
index 27f27ad..ac5918a 100644
--- a/apps/web/src/notes/editor.ts
+++ b/apps/web/src/notes/editor.ts
@@ -3,7 +3,8 @@ import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
 import { markdownKeymap, markdownLanguage, pasteURLAsLink } from '@codemirror/lang-markdown';
 import { yamlFrontmatter } from '@codemirror/lang-yaml';
 import { HighlightStyle, syntaxHighlighting } from '@codemirror/language';
-import { EditorView, keymap } from '@codemirror/view';
+import { EditorState } from '@codemirror/state';
+import { EditorView, type KeyBinding, keymap } from '@codemirror/view';
 import { tags } from '@lezer/highlight';
 
 // A note's parts in ink only, as §7 asks: weight, slant and the muted ink set them apart, never a colour.
@@ -19,31 +20,58 @@ const inkOnly = HighlightStyle.define([
   },
 ]);
 
+/** The editor's note page, which takes its text and saves it (decision 402). */
+export interface EditorPage {
+  /** Takes the editor's text after each change. */
+  edit(text: string): void;
+  /** Saves the editor's text. */
+  save(): void;
+  /** Whether a save runs; the editor takes no change until it ends, so the text saved is the text shown. */
+  readonly busy: boolean;
+}
+
 /**
  * Shows text, a note's Markdown, in a CodeMirror editor in the element, and gives the editor the focus (decision 401):
  * Markdown as GitHub writes it, after the note's YAML frontmatter, with its lines wrapped and undo. Enter carries a list
  * or a quote on to the next line, and a URL pasted over text links it. Tab leaves the editor, as it leaves any field.
- * The editor goes with the element.
+ * ⌘S, or Ctrl+S, saves, rather than the browser saving the page. The editor goes with the element.
  *
  * The bare Markdown language, without lang-markdown's markdown(), which would add HTML's, CSS's and JavaScript's for
  * the HTML in a note: 150 kB more in the editor's chunk.
  */
-export function noteEditor(text: string): Attachment<HTMLElement> {
+export function noteEditor(text: string, page: EditorPage): Attachment<HTMLElement> {
   return (parent) => {
     const view = new EditorView({
       parent,
       doc: text,
       extensions: [
         history(),
-        keymap.of([...markdownKeymap, ...defaultKeymap, ...historyKeymap]),
+        keymap.of([saveKey(page), ...markdownKeymap, ...defaultKeymap, ...historyKeymap]),
         yamlFrontmatter({ content: markdownLanguage }),
         pasteURLAsLink,
         syntaxHighlighting(inkOnly),
         EditorView.lineWrapping,
         EditorView.contentAttributes.of({ 'aria-label': 'Markdown' }),
+        EditorState.changeFilter.of(() => !page.busy),
+        EditorView.updateListener.of((update) => {
+          if (update.docChanged) {
+            page.edit(update.state.doc.toString());
+          }
+        }),
       ],
     });
     view.focus();
     return () => view.destroy();
   };
 }
+
+// ⌘S, or Ctrl+S, which saves; CodeMirror then takes the key, so the browser doesn't save the page as well.
+function saveKey(page: EditorPage): KeyBinding {
+  return {
+    key: 'Mod-s',
+    run: () => {
+      page.save();
+      return true;
+    },
+  };
+}
diff --git a/apps/web/src/notes/labels.test.ts b/apps/web/src/notes/labels.test.ts
index 887b668..75af21d 100644
--- a/apps/web/src/notes/labels.test.ts
+++ b/apps/web/src/notes/labels.test.ts
@@ -1,6 +1,7 @@
 import { expect, test } from 'vitest';
 
-import { countLabel, notesSummary, syncLabel } from './labels';
+import { countLabel, notesSummary, saveLabel, syncLabel } from './labels';
+import type { SaveStatus } from './shown.svelte';
 import type { Status } from './state.svelte';
 
 test.each([
@@ -30,3 +31,13 @@ test.each<{ status: Status; want: string }>([
 ])('labels $status.kind as "$want"', ({ status, want }) => {
   expect(syncLabel(status)).toBe(want);
 });
+
+test.each<{ status: SaveStatus; want: string }>([
+  { status: 'idle', want: '' },
+  { status: 'saving', want: 'Saving…' },
+  { status: 'saved', want: 'Saved' },
+  { status: 'changed', want: 'Not saved: the note has changed since it loaded' },
+  { status: 'failed', want: 'Save failed' },
+])('labels the save $status as "$want"', ({ status, want }) => {
+  expect(saveLabel(status)).toBe(want);
+});
diff --git a/apps/web/src/notes/labels.ts b/apps/web/src/notes/labels.ts
index b1a13de..576f09b 100644
--- a/apps/web/src/notes/labels.ts
+++ b/apps/web/src/notes/labels.ts
@@ -1,4 +1,5 @@
 import { timeLabel } from '../shell/clock';
+import type { SaveStatus } from './shown.svelte';
 import type { Status } from './state.svelte';
 
 /** A number of notes: "1 note", "12 notes". */
@@ -24,3 +25,19 @@ export function syncLabel(status: Status): string {
       return '';
   }
 }
+
+/** What the editor's last save did: "Saving…", "Saved", why it saved nothing, or "Save failed"; blank before a save. */
+export function saveLabel(status: SaveStatus): string {
+  switch (status) {
+    case 'saving':
+      return 'Saving…';
+    case 'saved':
+      return 'Saved';
+    case 'changed':
+      return 'Not saved: the note has changed since it loaded';
+    case 'failed':
+      return 'Save failed';
+    default:
+      return '';
+  }
+}
diff --git a/apps/web/src/notes/shown.svelte.ts b/apps/web/src/notes/shown.svelte.ts
index 2636e0d..498d1ec 100644
--- a/apps/web/src/notes/shown.svelte.ts
+++ b/apps/web/src/notes/shown.svelte.ts
@@ -1,23 +1,35 @@
 import { untrack } from 'svelte';
+import type { Attachment } from 'svelte/attachments';
 
-import { fetchNote } from './api';
+import { fetchNote, saveNote } from './api';
 import type { RenderedNote } from './render';
 import type { NotesState } from './state.svelte';
 import type { Note } from './tree';
 
 /** The note as its page has it: loading, missing from the vault, failed to load, or loaded and rendered. */
-type Body = { kind: 'loading' | 'missing' | 'failed' } | { kind: 'loaded'; markdown: string; note: RenderedNote };
+type Body =
+  | { kind: 'loading' | 'missing' | 'failed' }
+  | { kind: 'loaded'; markdown: string; version: string; note: RenderedNote };
+
+/** The editor's last save: running, or how it ended; changed when the note had changed since it loaded. */
+export type SaveStatus = 'idle' | 'saving' | 'saved' | 'changed' | 'failed';
 
 /**
- * The note that a note's page shows: the note once it loads, and whether the editor shows in its place. The page takes
- * a new one for each note it goes to, so the answer for a note it has left changes nothing.
+ * The note that a note's page shows: the note once it loads, whether the editor shows in its place, and the editor's
+ * save (decision 402). The page takes a new one for each note it goes to, so the answer for a note it has left changes
+ * nothing.
  */
 export class ShownNote {
   body = $state.raw<Body>({ kind: 'loading' });
   /** Whether the note shows in the editor, in place of its rendered text. A note's page opens with the text. */
   editing = $state(false);
+  status = $state<SaveStatus>('idle');
   readonly #note: Note;
   readonly #notes: NotesState;
+  /** The editor's text since its last change; undefined while it has none. */
+  #text: string | undefined;
+  /** The Edit button, which turns into Cancel. */
+  #button: HTMLButtonElement | undefined;
 
   /** The note, and the app's state for the Notes pages, whose list the note's links need. */
   constructor(note: Note, notes: NotesState) {
@@ -25,6 +37,16 @@ export class ShownNote {
     this.#notes = notes;
   }
 
+  /** Whether a save runs; until it ends, the editor takes no change, and Save and Cancel wait. */
+  get busy(): boolean {
+    return this.status === 'saving';
+  }
+
+  /** An attachment for the Edit button, which turns into Cancel. */
+  readonly button: Attachment<HTMLButtonElement> = (button) => {
+    this.#button = button;
+  };
+
   /** Loads the note's file, the renderer, a chunk of its own, the first time a note shows, and the vault's list. */
   async load(): Promise<void> {
     this.body = await this.#fetch();
@@ -32,25 +54,73 @@ export class ShownNote {
 
   /**
    * Edit turns into Cancel and back: one button, which keeps the focus. It takes the focus itself, which WebKit doesn't
-   * give a button on a click (plan §6.8), so the focus doesn't go with the editor.
+   * give a button on a click (plan §6.8), so the focus doesn't go with the editor. Edit starts from the note's text.
    */
-  toggle(button: HTMLButtonElement): void {
-    button.focus();
+  toggle(): void {
+    if (this.busy) {
+      return;
+    }
+    this.#button?.focus();
+    this.#text = undefined;
+    this.status = 'idle';
     this.editing = !this.editing;
   }
 
+  /** Takes the editor's text after each change. */
+  edit(text: string): void {
+    this.#text = text;
+  }
+
+  /**
+   * Saves the editor's text, if the note hasn't changed since it loaded, then shows the note with it and gives the
+   * focus to Edit. A note that has changed, or a failed save, keeps the editor open with the text. With no change to
+   * save, it only closes the editor.
+   */
+  async save(): Promise<void> {
+    const body = this.body;
+    const text = this.#text;
+    if (this.busy || !this.editing || body.kind !== 'loaded') {
+      return;
+    }
+    if (text === undefined || text === body.markdown) {
+      this.#close('idle');
+      return;
+    }
+    this.status = 'saving';
+    try {
+      // Rendered first, so that a save that went through is never said to have failed.
+      const { renderNote } = await import('./render');
+      const note = renderNote(text, this.#note, this.#notes.files ?? []);
+      const version = await saveNote(this.#note.path, text, body.version);
+      if (version === undefined) {
+        this.status = 'changed';
+        return;
+      }
+      this.body = { kind: 'loaded', markdown: text, version, note };
+      this.#close('saved');
+    } catch {
+      this.status = 'failed';
+    }
+  }
+
+  #close(status: SaveStatus): void {
+    this.#button?.focus();
+    this.status = status;
+    this.editing = false;
+  }
+
   async #fetch(): Promise<Body> {
     try {
       // Untracked, or the list's arrival would run the page's effect, and load the note, again.
       const listed = untrack(() => this.#notes.load());
-      const [markdown, { renderNote }] = await Promise.all([fetchNote(this.#note.path), import('./render'), listed]);
-      if (markdown === undefined) {
+      const [file, { renderNote }] = await Promise.all([fetchNote(this.#note.path), import('./render'), listed]);
+      if (file === undefined) {
         return { kind: 'missing' };
       }
       const files = this.#notes.files;
       return files === undefined
         ? { kind: 'failed' }
-        : { kind: 'loaded', markdown, note: renderNote(markdown, this.#note, files) };
+        : { kind: 'loaded', ...file, note: renderNote(file.markdown, this.#note, files) };
     } catch {
       return { kind: 'failed' };
     }
diff --git a/apps/web/src/notes/shown.test.ts b/apps/web/src/notes/shown.test.ts
new file mode 100644
index 0000000..b08c4ee
--- /dev/null
+++ b/apps/web/src/notes/shown.test.ts
@@ -0,0 +1,190 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+import { renderNote } from './render';
+import { ShownNote } from './shown.svelte';
+import { NotesState } from './state.svelte';
+import { noteAt } from './tree';
+
+const toDo = noteAt('/notes/Daily/To%20do')!;
+const files = ['Daily/To do.md', 'Inbox.md'];
+const markdown = '# To do\n\n- [ ] Tune';
+const ticked = '# To do\n\n- [x] Tune';
+const loaded = '"1"';
+const saved = '"2"';
+
+let fetchMock: ReturnType<typeof vi.fn<typeof fetch>>;
+
+beforeEach(() => {
+  fetchMock = vi.fn<typeof fetch>().mockResolvedValueOnce(new Response(markdown, { headers: { ETag: loaded } }));
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  document.body.replaceChildren();
+});
+
+// The note, loaded with the vault's list, and its Edit button on the page.
+async function shownNote() {
+  const notes = new NotesState();
+  notes.files = files;
+  const shown = new ShownNote(toDo, notes);
+  const button = document.createElement('button');
+  document.body.append(button);
+  shown.button(button);
+  await shown.load();
+  return { shown, button };
+}
+
+// Presses Edit, and puts the focus in a field, as the editor takes it.
+function open(shown: ShownNote): void {
+  shown.toggle();
+  const field = document.createElement('textarea');
+  document.body.append(field);
+  field.focus();
+}
+
+// The note in the editor, its text changed to ticked.
+async function edited() {
+  const { shown, button } = await shownNote();
+  open(shown);
+  shown.edit(ticked);
+  return { shown, button };
+}
+
+function answer(status: number, version?: string): Response {
+  return new Response(null, { status, headers: version === undefined ? {} : { ETag: version } });
+}
+
+// The If-Match and the body of the save's request.
+function sent(call: number) {
+  const init = fetchMock.mock.calls[call]?.[1];
+  return { ifMatch: new Headers(init?.headers).get('If-Match'), body: init?.body };
+}
+
+test('keeps the note’s version, from its ETag, with its text', async () => {
+  const { shown } = await shownNote();
+
+  expect(shown.body).toEqual({ kind: 'loaded', markdown, version: loaded, note: renderNote(markdown, toDo, files) });
+});
+
+test('saves the text if the note is still at its version, then shows it, says so and gives Edit the focus', async () => {
+  const { shown, button } = await edited();
+  fetchMock.mockResolvedValueOnce(answer(204, saved));
+
+  const saving = shown.save();
+  expect(shown.status).toBe('saving');
+  expect(shown.busy).toBe(true);
+  await saving;
+
+  expect(fetchMock).toHaveBeenLastCalledWith(
+    '/api/notes/files/Daily/To%20do.md',
+    expect.objectContaining({ method: 'PUT' })
+  );
+  expect(sent(1)).toEqual({ ifMatch: loaded, body: ticked });
+  expect(shown.body).toEqual({
+    kind: 'loaded',
+    markdown: ticked,
+    version: saved,
+    note: renderNote(ticked, toDo, files),
+  });
+  expect(shown.editing).toBe(false);
+  expect(shown.status).toBe('saved');
+  expect(button).toHaveFocus();
+});
+
+test('Edit starts again from the saved text, and the next save sends the version the last one gave', async () => {
+  const { shown } = await edited();
+  fetchMock.mockResolvedValueOnce(answer(204, saved)).mockResolvedValueOnce(answer(204, '"3"'));
+  await shown.save();
+
+  shown.toggle();
+  expect(shown.status).toBe('idle');
+  shown.edit(`${ticked}\n- [ ] Sing`);
+  await shown.save();
+
+  expect(sent(2)).toEqual({ ifMatch: saved, body: `${ticked}\n- [ ] Sing` });
+});
+
+test.each([
+  { name: 'with no change', change: (_: ShownNote) => undefined },
+  { name: 'with its changes undone', change: (shown: ShownNote) => shown.edit(markdown) },
+])('only closes the editor $name', async ({ change }) => {
+  const { shown, button } = await shownNote();
+  open(shown);
+  change(shown);
+
+  await shown.save();
+
+  expect(fetchMock).toHaveBeenCalledOnce();
+  expect(shown.editing).toBe(false);
+  expect(shown.status).toBe('idle');
+  expect(button).toHaveFocus();
+});
+
+test('saves nothing while the editor is closed', async () => {
+  const { shown } = await shownNote();
+
+  await shown.save();
+
+  expect(fetchMock).toHaveBeenCalledOnce();
+  expect(shown.status).toBe('idle');
+});
+
+test('keeps the editor and its text when the note has changed since it loaded, and the next try sends it again', async () => {
+  const { shown } = await edited();
+  fetchMock.mockResolvedValue(answer(412));
+
+  await shown.save();
+  expect(shown.status).toBe('changed');
+  expect(shown.editing).toBe(true);
+  expect(shown.body).toMatchObject({ markdown, version: loaded });
+  await shown.save();
+
+  expect(sent(2)).toEqual({ ifMatch: loaded, body: ticked });
+});
+
+test.each([
+  { name: 'answers with an error', answer: () => Promise.resolve(answer(500)) },
+  { name: 'can not be reached', answer: () => Promise.reject(new TypeError('Failed to fetch')) },
+])('keeps the editor and says the save failed when the gateway $name', async ({ answer }) => {
+  const { shown } = await edited();
+  fetchMock.mockImplementationOnce(answer);
+
+  await shown.save();
+
+  expect(shown.status).toBe('failed');
+  expect(shown.editing).toBe(true);
+  expect(shown.body).toMatchObject({ markdown, version: loaded });
+});
+
+test('Cancel and Save wait while a save runs', async () => {
+  const { shown } = await edited();
+  const put = Promise.withResolvers<Response>();
+  fetchMock.mockReturnValueOnce(put.promise);
+  const saving = shown.save();
+  await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+
+  shown.toggle();
+  await shown.save();
+  expect(shown.editing).toBe(true);
+  expect(fetchMock).toHaveBeenCalledTimes(2);
+  put.resolve(answer(204, saved));
+  await saving;
+
+  expect(shown.status).toBe('saved');
+});
+
+test('Cancel drops the last save’s word with the edits', async () => {
+  const { shown } = await edited();
+  fetchMock.mockResolvedValueOnce(answer(500));
+  await shown.save();
+
+  shown.toggle();
+
+  expect(shown.editing).toBe(false);
+  expect(shown.status).toBe('idle');
+  shown.toggle();
+  await shown.save();
+  expect(fetchMock).toHaveBeenCalledTimes(2);
+});
diff --git a/docs/plan.md b/docs/plan.md
index d7b63cc..f4b5baa 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -1783,7 +1783,7 @@ Decisions 400 to 499 are the vault session's: `vault-edit-sync`, then `copilot-p
      - **Rejected**: CodeMirror's `basicSetup` and the `codemirror` package, which add line numbers, folding, autocompletion, search and more that a note doesn't need; CodeMirror's drawn selection (`drawSelection`); a highlight in colours, against §7; `markdown()`, for its 150 kB.
 402. **A note's save** (`note-page-state`, `note-save`): the lead's choices (2026-10-30), for the user to review.
      - **The page's state first**: a note's page keeps the note it shows, its loading and whether the editor shows in a class of its own, `ShownNote`, rather than in its component, since the save's logic, which renders the note again, belongs in a `.ts` file, where the gates can read it. The page takes a new one for each note it goes to, which drops the edits and any late answer for the note it has left. `note-page-state` moves the state there with no change in behaviour, before `note-save` adds the save.
-     - **The save**: Save sends the editor's text with `PUT /api/notes/files/<path>`, `text/markdown; charset=utf-8`, with `If-Match` naming the version the page loaded, the note's `ETag` (decision 400). On a 204 the page shows the saved note at once, rendered from the text it sent, takes the answer's `ETag` as the note's version, says "Saved", and gives the focus to Edit; the next Edit starts from the saved text. Save with the text unchanged only closes the editor. ⌘S, or Ctrl+S, in the editor saves too, rather than open the browser's Save Page.
+     - **The save**: Save follows Cancel, so the button that turns keeps its place, and Shift-Tab from the editor reaches Save first. It sends the editor's text with `PUT /api/notes/files/<path>`, `text/markdown; charset=utf-8`, with `If-Match` naming the version the page loaded, the note's `ETag` (decision 400). On a 204 the page shows the saved note at once, rendered from the text it sent, takes the answer's `ETag` as the note's version, says "Saved", and gives the focus to Edit; the next Edit starts from the saved text. The page renders the text before it sends it, so a renderer that fails to load stops the save before it starts, rather than a save that went through being reported as failed. Save with the text unchanged only closes the editor. ⌘S, or Ctrl+S, in the editor saves too, rather than open the browser's Save Page. What the save did shows on a line under the buttons, as the sync's state does on the notes' list.
      - **While it runs**: Save and Cancel wait, `aria-disabled` rather than disabled so the focus stays on them, as in the todos' editor, and the editor takes no typing, so the text saved is the text shown.
      - **When it fails**: a 412, from a note that has changed since it loaded, keeps the editor open with the user's text and says so; any other failure keeps it too and says the save failed. What the user can then do about the change comes with the store's step and its §3 conflict rules. The buttons stay while the editor is open, even if a sync says that notes no longer saves.
      - **Rejected**: asking before Cancel or going to another note drops the edits, for now (decision 401); a Save in the editor's chunk, which a chunk that fails to load would take with it; a read of the note after the save, which would show the old text until git-sync has the new one.

From aa7784c65b4498622e31c500bf9b96f28bcdf2b6 Mon Sep 17 00:00:00 2001
From: Bakhomious Basta <bakhomioussvp@gmail.com>
Date: Fri, 30 Oct 2026 03:16:00 +0100
Subject: [PATCH 2/2] docs: mark note-save done (#180)

---
 docs/plan.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/plan.md b/docs/plan.md
index f4b5baa..81c938d 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -198,7 +198,7 @@ The v1.2 design in §4 to §6 stays as reference. A piece of it is built only wh
 | `note-etag` | notes answers each note with its version as a strong `ETag`, the SHA-256 of its bytes, and a matching `If-None-Match` with a 304 (decision 400) | Done (#169) |
 | `note-editor` | A note's page shows an Edit button once `GET /api/notes` says saving is set up; Edit shows the note's Markdown in a CodeMirror 6 editor, and Cancel shows the note again and drops the edits, which nothing saves yet (decisions 400, 401) | Done (#174) |
 | `note-page-state` | A note's page keeps the note it shows, its loading and whether the editor shows in a class of its own, `ShownNote`, in a `.ts` file where the gates can read it, ready for the save's logic; no change in behaviour (decision 402) | Done (#177) |
-| `note-save` | The editor's Save sends the note with `PUT /api/notes/files/<path>` and `If-Match`, the version from the note's `ETag`; a saved note shows at once, and a note changed since gets a 412, which keeps the user's text and says so (decisions 400 to 402) | Planned |
+| `note-save` | The editor's Save sends the note with `PUT /api/notes/files/<path>` and `If-Match`, the version from the note's `ETag`; a saved note shows at once, and a note changed since gets a 412, which keeps the user's text and says so (decisions 400 to 402) | Done (#180) |
 
 After these: the product phases (§8.2), each split into steps.
 
@@ -1285,7 +1285,7 @@ Every item is pending unless it says done. The service an item lands in is in br
   - `note-etag`: notes answers each note with its version as a strong `ETag`, and a matching `If-None-Match` with a 304 (decision 400). Done (#169).
   - `note-editor`: a note's page edits it in a CodeMirror 6 editor, once `GET /api/notes` says saving is set up, with no save yet (decisions 400, 401). Done (#174).
   - `note-page-state`: a note's page keeps its state in a class, `ShownNote`, with no change in behaviour (decision 402). Done (#177).
-  - `note-save`: the editor's Save, a `PUT` with `If-Match`, which keeps the user's text on a 412 (decisions 400 to 402).
+  - `note-save`: the editor's Save, a `PUT` with `If-Match`, which keeps the user's text on a 412 (decisions 400 to 402). Done (#180).
   - After the answer: the store behind the save, with the §3 conflict rules; new notes get unique names; history and rollback; and the way edits get back to the Mac, now that the laptop syncs from Gitea's read-only mirror (decision 151, §12).
 - `copilot-planner` [planner, web]. Needs `spike-copilot-sdk`, `vault-edit-sync`.
   - Chat UI with streaming, plan-mode sessions, resume, and plan preview.