fix(footnotes): guard insert against nested/bare definitions, skip definitions-only paste, doc + reorder fixes (#228)

Must-fix:
- insertInlineFootnote could glue a footnoteReference inside an EXISTING
  definition (nested footnotesList, or a bare footnoteDefinition with no list
  wrapper), which canonicalize then dropped as an orphan — silently losing the
  definition's prose. Now: (a) the body/notes boundary is computed from the first
  top-level block that IS or CONTAINS (recursively) a footnotesList/
  footnoteDefinition, not just a top-level list; and (b) the insertNodesAfterAnchor
  core skips footnotesList/footnoteDefinition subtrees entirely (skipSubtreeTypes),
  so an anchor whose only match is inside a definition -> inserted:false (clean
  abort, no write). Added tests: nested-definition, bare-definition, and
  body-before-nested-list-still-inserts.
- editor-ext footnote-canonicalize header listed `markdownToProseMirror` among the
  canonicalizing MCP paths; it is the NON-canonicalizing primitive. Replaced with
  `markdownToProseMirrorCanonical` (+ note that the plain primitive is for comment
  bodies) and added copy_page_content.
- Client paste: canonicalizePastedFootnotes now skips a definitions-ONLY paste
  (no footnoteReference anywhere) — canonicalizing it would strip the
  reference-less list and yield an EMPTY paste. Added a test.

Suggestions:
- docmost_transform now runs validateDocStructure/validateDocUrls on the RAW
  transform output BEFORE canonicalizeFootnotes (mirrors updatePageJson), so a
  too-deep doc gives the intended max-depth error instead of a stack overflow.
- docmost_transform tool description now states the RESULT is footnote-canonical
  (dryRun diff may show tidy-ups; idempotent after first run).
- insertFootnote: dropped the dead `result ? … : undefined` ternaries and the
  `as any` casts (result is always set by the time we return; the not-found path
  throws and aborts mutatePage). `const r = result!;`.

Tests / architecture:
- Added a LIVE-plugin golden case: the real footnoteSyncPlugin leaves a list with
  non-empty content after it in place, and canonicalize agrees (placement parity
  is now a driven property, not a hand-set expected).
- Added generateFootnoteId uuidv7 shape + uniqueness test.
- Item 9: added the ENFORCEMENT-RULE comments at the server parseProsemirrorContent
  and the MCP canonicalizer header (any NEW full-doc persist path MUST canonicalize;
  fragments/append/prepend and comment bodies MUST NOT). Kept per-call-site over a
  brittle grep CI test (the replace-vs-fragment + comment-vs-page nuance makes a
  single wrapper unsafe).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/editor-ext/src/lib/footnote/footnote-canonicalize.test.ts

@@ -308,6 +308,31 @@ describe('canonicalizeFootnotes golden parity with footnoteSyncPlugin', () => {
     });
   }
 
+  it('placement parity: the LIVE plugin leaves a list with NON-EMPTY content after it in place, and canonicalize agrees', () => {
+    // Drives the real footnoteSyncPlugin (not a hand-authored expected): a single
+    // canonical list with body content AFTER it must NOT be repositioned by the
+    // plugin, and the server canonicalizer must agree (step-6 placement parity).
+    const content = {
+      type: 'doc',
+      content: [
+        para({ type: 'text', text: 'a' }, ref('x')),
+        list(def('x', 'X')),
+        para({ type: 'text', text: 'epilogue' }),
+      ],
+    };
+    const steady = pluginSteadyState(content);
+    // The plugin did NOT move the list to the end: a non-empty paragraph follows it.
+    const types = steady.content.map((n: any) => n.type);
+    const listPos = types.indexOf(FOOTNOTES_LIST_NAME);
+    expect(listPos).toBeGreaterThanOrEqual(0);
+    expect(listPos).toBeLessThan(types.length - 1);
+    const after = steady.content[listPos + 1];
+    expect(after.type).toBe('paragraph');
+    expect(JSON.stringify(after)).toContain('epilogue');
+    // The canonicalizer is a byte-for-byte no-op on that steady state (parity).
+    expect(canonicalizeFootnotes(steady)).toEqual(steady);
+  });
+
   it('the canonicalizer and the editor agree on reference order and definition set', () => {
     const content = {
       type: 'doc',

packages/editor-ext/src/lib/footnote/footnote-canonicalize.ts

@@ -18,9 +18,11 @@ import {
  * `PageService` create/update (`parseProsemirrorContent` for the JSON/markdown/
  * HTML REST write paths), and the client markdown PASTE path
  * (`markdown-clipboard.ts`). (The MCP package mirrors this canonicalizer in
- * `packages/mcp/src/lib/footnote-canonicalize.ts` for its own write paths —
- * `markdownToProseMirror`, `update_page_json`, `docmost_transform`,
- * `insert_footnote` — see that file's header.) All of these are the root cause
+ * `packages/mcp/src/lib/footnote-canonicalize.ts` for its own FULL-document write
+ * paths — `markdownToProseMirrorCanonical` (the page markdown-import path; the
+ * plain `markdownToProseMirror` primitive used for COMMENT bodies does NOT
+ * canonicalize), `update_page_json`, `docmost_transform`, `insert_footnote`,
+ * `copy_page_content` — see that file's header.) All of these are the root cause
  * of the symptom in the issue: footnotes rendered out of order (`1, 4, 2, 3, …`),
  * a raw trailing `[^id]: …` block, and orphan definitions, all of which are
  * simply the result of content written PAST the canonicalizer.